Documenting packages

General Usage
1

I just created a new package but I’m having a lot of trouble getting the documentation to render with Documenter.jl. When I deploy it to GitHub pages it displays the readme instead of the index.md file in my docs/src directory and it only seems to be displaying raw html without the CSS elements. It also seems that the @autodocs macro isn’t working. I have an api.md file formatted as follows but the html page writes exactly what is in api.md instead of actually documenting the modules.

# API

```@autodocs
modules = [CausalELM, Estimators, Metalearners, Models, ActivationFunctions, Metrics, 
    CrossValidation]


Any help would be much appreciated.
2

you need to show us the repo so we can see what you did wrong

3

Sorry, I thought I included that. The repo is here.

4

you’re not deploying the docs at all.

You’re not supposed to track the docs/build directory in your main branch. And at the moment the gh-pages branch is a copy of your main branch instead of being a doc branch

Here’s a good example:

1 Like
5

I uncommented and fixed the deploydocs block but it still isn’t finding the right files.

6

I would recommend using the plugin from PkgTemplates.jl to setup a GitHub action to build and deploy the docs for you, as it does all the hard work. Even if you have already created your project, you can grab the workflow easily enough.

You just need a .yml file in .github/workflows. An example one is here - Experimenter.jl/CI.yml at main · JamieMair/Experimenter.jl · GitHub.

You can remove the block for testing and just use the documentation one if you like, this should deploy the docs on every commit to main.

EDIT: It seems you already have a CI.yml file, you can just add the documentation task from the link above and it should handle the docs for you, just like the testing.

1 Like
7

I would also recommend deleting the docs/build from git and adding it to the gitignore.

It illustrates that the run locally seems to run at least, though I can not see where it would have generated a api.html file, is that maybe even an outdated run of the docs in build/ (one reason more to delete it :wink: ) ?

8

if you look at this branch, it’s still just a copy of your main branch, this is wrong.

you may try delete this branch all together and try re-trigger the CI

9

Thank you all for looking at my repo. I ended up creating a new package structure with PkgTemplates as @jmair suggested. I also realized that I was using docs/build instead of root for my gh-pages deployment and changing that fixed the problem after I created the new package structure.

2 Likes