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 index.md.
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/index.md 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?
I have created a file named documentation.yml in the JMtk15/.github/workflows directory containing the following lines:
name: Documentation
on:
push:
branches:
- main
tags: '*'
pull_request:
jobs:
build:
permissions:
contents: write
runs on: macos
steps:
- uses: actions/checkout@v2
- uses: julia-actions/setup-julia@v1
with:
version: '1.8'
- name: Install dependencies
run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
- name: Build and deploy
env:
Questions:
Is macos the proper name and spelling (macOs, Ventura?) of the Mac operating system?
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?
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??
Will that setup automatically update the documentation in the future, when more functions will be added?
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.
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/index.md. 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?
docs/src/index.md 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).
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.
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).
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: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/.
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.
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 index.md 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?
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: https://documenter.juliadocs.org/stable/man/hosting/#The-deploydocs-Functionc
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.
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 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.
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…
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.
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?
One thing that still seems to be wrong are the ”edit on GitHub” links in the docs, they refer to https://github.com/mmverstraete/JMtk15.jl/ 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
