Docstrings do not appear in the project documentation


I have just pushed a new Julia project (GitHub - mmverstraete/JMtk15: Julia wrapper functions to the C functions of the MISR Toolkit (Mtk) Version 1.5.) on GitHub. It is currently incomplete (work in progress), but it contains already an initial set of 64 wrapper functions to C functions of the NASA MISR Toolkit (GitHub - nasa/MISR-Toolkit: an API facilitating the access of MISR standard product files), together with a set of test functions.

Each function includes a docstring header, and the documentation was setup as suggested in the Documenter.jl package, i.e., with a docs/ directory containing the file make.jl and a docs/src/ subdirectory containing the file

On my local computer, the HTML documentation is complete and accessible from docs/build/index.html in a web browser, however on GitHub the document main/docs/src/ only shows the list of functions, not the docstrings themselves. There must be something improperly setup either locally or remotely (or both) that prevents the docstrings from being displayed in the JMtk15 Package Documentation file on GitHub.

As an aside, each of the test functions already available in test/src also contains a docstring. How can I setup (locally and remotely) a documentation file for those test functions, where the sources are in test/src?

Thanks for suggestions on this matter.

The fast short answer is: You are missing the GitHub action to generate / publish / push that on GitHub, see Hosting Documentation · Documenter.jl

Thanks a lot, @kellertuer!

I have created a file named documentation.yml in the JMtk15/.github/workflows directory containing the following lines:

name: Documentation

      - main
    tags: '*'

      contents: write
    runs on: macos
      - uses: actions/checkout@v2
      - uses: julia-actions/setup-julia@v1
          version: '1.8'
      - name: Install dependencies
        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
      - name: Build and deploy


  1. Is macos the proper name and spelling (macOs, Ventura?) of the Mac operating system?

  2. I am unsure how to complete the last line (after env:), because I use the Git Credential Manager to connect to Git Hub, and I am not aware of a GITHUB_TOKEN or DOCUMENTER_KEY. Where do I find that information, or how do I set that up?

  3. After updating that last line and after having added this YML file in the proper place, is it sufficient to push it to GitHub, or do I need to execute any other process to update the on-line documentation??

  4. Will that setup automatically update the documentation in the future, when more functions will be added?

Thanks again for your help.

I am usually leazy and steal from (my own) previous files, like Manopt.jl/documenter.yml at master · JuliaManifolds/Manopt.jl · GitHub which runs on Ubuntu (usually faster in start time, but you could (see Manopt.jl/ci.yml at master · JuliaManifolds/Manopt.jl · GitHub ) for example use macOS-latest.

You can use either of these methods, see Hosting Documentation · Documenter.jl

place it with your other actions in .github/workflows/ (like the ones I “stole” from above).

That depends on the on: keyword. Currently you branch should be called main then that branch should generate the dev version. which always renders when you push to the main branch on Github.
But for every registered version, also a doc is created, see the very bottom in the menu “Version” dropdown e.g. at Home · Manopt.jl . For that to trigger correctly see GitHub - JuliaRegistries/TagBot: Creates tags, releases, and changelogs for your Julia packages when they're registered (and setting that up for the first time when registering versions takes a bit). Then – when ever you register a new version in the Julia Registry, also new docs are rendered.

Hi @kellertuer.

I have saved and pushed the file .github/workflows/documentation.yml on GitHub, but do not see any change in the documentation file docs/src/ I did enable three write permissions, for actions, contents and deployments, but I don’t know whether those are the most appropriate choices…

I don’t understand either what is meant by the dev version: is that another branch?

BTW, I have not taken any step (yet) to register this JMtk15 package, unless that is taking place automatically.

I found lots of pages of documentation with countless options, but no clear instruction about how to simply setup a new project to automatically generate the documentation… Could you let me know what am I still missing, if anything, or what to do to force the re-creation of the documentation on GitHub?

Thanks again for your support.

docs/src/ will never change (unless you edit it). Instead in the docs/build folder all rendered html-pages are pushed to the gh-pages branch.

As long as it is not registered, you only get the dev version, but that is a rendered one.

For now you have to read the error message – the documenter workflow does not even run, since

your yaml is not formatted correctly.
If that does run we have to check whether the run of docs/make in the CI is successful and if not what it does report (I for example – for good reasons – can not see your GitHub and/or Documenter keys).
The first thing where you see that it was successful is when the gh-pages branch exists. Then you still have to activate that as the rendered homepage in the repository settings (host gh-pages).

Thanks, @kellertuer, for your precious help.

Apologies for asking perhaps trivial questions, but how did you make that error message appear? I never saw it on my computer. Should this .yml file be executed or activated in any way, after being created? What process determined that there was a syntax error?

It looks like the runs on setting is incorrect, so I’m back to the earlier question: what is the appropriate option to point to the Apple operating system (macos, macOs, macOS, something else), or, more specifically, where in the documentation can I see the values that are allowed for this key?

Assuming that line will be corrected soon, the next question relates to CI: does this refer to Continuous Integration? Is that necessary to generate the documentation? If so, what do I need to do to implement it?

Also, what are Documenter keys, and where can I find those, if there are any already defined?

I’ll be glad to run any diagnostic that may help resolve these questions, and will report on the outcomes.

Magic! I just did magic.

The easiest, is to check

the last run actions.

Concerning the choice – I am not sure why you want it to run in apple systems, but you can still “steal” the setup from Manopt.jl/documenter.yml at master · JuliaManifolds/Manopt.jl · GitHub and change ubuntu-latest to macOS-latest as mentioned earlier. You can also check how we did the runs on there.

Yes with CI I meant Continuous Integration – maybe more precise all GitHub actions. They are triggered when you push something to master – and since they try to run and error – that is already fine.

For the documenter keys please read the Documentation Hosting page carefully I linked already twice above, they are needed (basically) so Documenter has the rights to push to the gh-pages branch – and create it in the first place. Because the only person having push-rights currently is – you. With the Key you grant that GitHub Action exactly these rights. The hosting page above also states where to upload the keys (and later find them).

Finally: Yes these first steps take a while especially for the first setup that you ever did – they also take me a while if I did not do that for a year and start a new package. But once it is set up, the Docs are generated completely automatic on every push (unless you do bugs in your make.jl which you also can check locally).

Thanks to @kellertuer, the Magician! :wink:

OK, I did look again at the ‘steal file’ you mentioned earlier, and found the line spelled out as runs-on: ubuntu-latest. I was assuming that this meant you are working on a Linux platform under Ubuntu, so that’s why the corresponding line in my documentation.yml file read runs on: macOS-latest. However, I now suspect this setting refers to a GitHub machine where a process to generate the documentation may be running: if that’s the case, I don’t particularly care which machine or operating system is used for that purpose, as long as the outcome is correctly produced. I have thus updated my file to also set this key to runs-on: ubuntu-latest.

After pushing this new version on GitHub, I see that the action pages build and deployment completed correctly (though I did not notice any change in the documentation files), while another action (Documentation #3) generated the following cryptic message"

Node.js 12 actions are deprecated. Please update the following actions to use Node.js 16: actions/checkout@v2. For more information see:

I have no idea what those Node xx refer to… I looked at the URL and found a number of examples but since I don’t understand that message (I never asked to use Node 12 in the first place), I am not sure how to correctly edit that file to force using Node 16

For the node js: GitHub actions have versions as well and you run
- uses: actions/checkout@v2
but could update to
- uses: actions/checkout@v3
which removes the warning.

But you still have an error, now one within Julia (but at least they run the Julia already) see Update 'runs on' in documentation.yml. · mmverstraete/JMtk15@aaff59f · GitHub

So you seem to miss a file? (Look at those logs from now on until they report that they do push and such (and you get the gh-pages branch). Again the Hosting page I linked has most cases that can occur here.

Thanks, @kellertuer: this is enlightening! I have now

  • updated the file documentation.yml to refer to actions/checkout@v3,

  • updated the file to refer only to functions that have effectively been pushed on GitHub: there were three files that had not been published yet (they are not ready) and one that is already available but was not included,

  • updated the main module JMtk15, which also referred to a couple of files not yet uploaded, and

  • pushed those files to GitHub.

It took a few iterations to get everything right, but at least there are no more errors.

The next issue, now, is that the file

shows the HTML code itself, rather than a nicely formatted document: what do I need to do to visualize it without the formatting codes, and what would be the proper URL or pointer for users to also see that documentation properly formatted?

Thanks a lot for walking me through this maze…

…but you also „cheated“. The folder you linked is the documentation you generated locally, committed to git and pushed to the repo. That should not be pushed. And it was not generated by the CI/Github Action. See also the warning directly above

You action does run without errors, but it does not yet push to the gh-pages branch it seems, see

(it also tells you some warnings about missing docs, but that you can solve locally)
If you compare that log to a successful one, e.g.

you see that there are more steps that should happen. One first thing that I do see is that this file

is missing the deployment call, cf.

I am sorry if I am reaeating myself but all my last posts are all written in the very beginning:
Please read that whole page carefully (ok you can skip the Travis CI part and just read the GitHub Actions part of course).That page really explains all the necessary steps. Also the deploydocs and the secrets.

Hi @kellertuer,

Sorry for this confusing state: I’m learning by doing, but navigating in the dark because I’m missing an overall grasp of the general principles and strategy to create the documentation. I initially thought it would be sufficient to generate it locally on my computer, and then upload it to GitHub from time to time… Hopefully this will be less painful next time around!

Anyway, I’ve now

  • included the deploydocs line at the bottom of the make.jl file,

  • added a docs/build/ line to the .gitignore file, as recommended in the documentation,

  • specified to deploy from the main branch, and from the /docs directory specifically in the GitHub Pages settings.

I also saw the message indicating that some docstrings had been found but not included, and that’s fine for the time being: they relate to low-level functions of Mtk that I do not control and should not be of interest to the users.

Anyway, I then

  • regenerated the documentation locally,

  • staged and committed the changes to docs/make.jl and .gitignore locally, and

  • pushed those changes on GitHub.

That process did not generate any error messages, though inspecting the logs of Actions:

  • the log pages build and deployment, in the section Upload artifact, shows a number of messages of the type chmod: changing permissions of './docs/_site': Operation not permitted: is this expected, or should I do anything about it?

  • the log Update make.jl and .gitignore, in the section Build and deploy, includes a hint about using main rather than master as the primary branch. I thought this was already the case, but I re-issued the command git config --global init.defaultBranch main locally anyway.

  • Later on in the same section, there appears to be a complaint about the missing gh-pages branch, but I assume it has now been created, since the main project page indicates that there are two branches.

I’m not sure what to do next, though…

Thanks a lot again for your patience!

I think you have to set this to deploy from gh-pages branch because Documenter.jl is pushing the output of the deploydocs into this branch and this is what you would like to show in the Documentation homepage.
And after your last github action run, the gh-pages branch has been created and filled with some files.

1 Like

Hi @Fliks,

Thanks for this suggestion: I have modified the project Settings/Pages to deploy from the gh-pages branch, but I now get the following error message:

Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/style.scss': No such file or directory @ dir_chdir - /github/workspace/docs

I am not sure what that means, or what to do next…

Comparing actions (again with a working one) see yours

vs mine

make sure your Pages setup is correct, that is something like

My guess (magic!) is that you chose docs/ here but that is where your docs are (unrendered) on the main branch. for the gh-pages branch chose the root.

Hi @kellertuer,

Indeed, your magic worked again! I have reset the source to /roots, and that removed the error. My key question now, is what to do next, or where to find the properly formatted documentation, if it has been generated. Also, do I need to cleanup anything left over form all those trials?

Just below the setup for Pages you should see the URL where the pages are published - but luckily I am a magician (ok, no, I just know the pattern ;))

works fine.

cleanup is hard to say, because I have not looked at what “trash” might be left from all the tries in the repo.

One thing that still seems to be wrong are the ”edit on GitHub” links in the docs, they refer to but your repo is missing the .jl – I am not sure where to set that up, probably in the makedocs or deploydocs.

Oh and for the docs (but you see these warnings also then you run that locally)

8 of your functions have docstrings that are not yet included in the docs – the list is even given :slight_smile:

1 Like