open-source-rover
open-source-rover copied to clipboard
nasa-jpl
Documentation build proof-of-concept using MkDocs
Documentation build proof-of-concept using MkDocs.
Two MkDocs themes have been investigated:
- readthedocs #360 Currently deployed
- ~~Material #318~~
Preference has been indicated for #360 as it supports versioned documentation.
Documentation demo is hosted at https://osr-demo.readthedocs.io/ (Read the docs)
Todo
The following fixes should be fixed as separate issues and merged before this issue (#317). See Bugs section below for an explanation.
- [ ] Make GitHub.com links absolute #361
- [ ] Fix whitespace-only changes to the Markdown documents #362
After this (#317) is merged, and before documentation can be deployed to Read the Docs:
- [ ] Decide on a subdomain for the project. Ideas:
osr.readthedocs.io,jpl-osr.readthedocs.io, ornasa-jpl-osr.readthedocs.io. - [ ] An admin of nasa-jpl will need to Sign up for Read the Docs and import nasa-jpl/open-source-rover to Read the Docs.
Bugs
There are currently a few bugs in the rendered HTML. However, these can all be fixed with whitespace-only changes to the Markdown documents:
- Empty lines between paragraphs and lists
- Empty lines between paragraphs and tables
- Consistent list indentation
- Remove leading whitespace from headings and paragraphs
The above changes are compatible with the GitHub flavoured Markdown specification meaning rendering of Markdown on GitHub.com will not be affected.
For links to GitHub directories to work:
- Make GitHub links absolute
As it turns out, all GitHub links bar one in electrical/README.md are absolute.
Change to GitHub link in electrical/README.md
[the PCB folder](/electrical/pcb/)
should be changed to:
[the PCB folder](https://github.com/nasa-jpl/open-source-rover/tree/master/electrical/pcb)
Requirements
The proof-of-concept was built to the following requirements:
- no changes to the directory structure of the project
- allow the documentation to be displayed/used as it currently is on GitHub.com
- add only a few additional files to the codebase
- automatic build and deploy
Related issues
This proposal may resolve #106.
I haven't looked through all documentation generated by this but at a first glance it looks really nice. I have a few questions as I'm not familiar with mkdocs much.
- what is the upkeep for this? Is it auto updated from updates to the Readme docs?
- does it support release versions? (not necessary, but could be nice to keep legacy versions of the documentation)
- are there any other changes we'd need to look at making to support this?
what is the upkeep for this? Is it auto updated from updates to the Readme docs?
Yes. The built site is auto updated from the Readme docs.
Read the docs has a GitHub webhook to trigger automatic builds. Builds are triggered on push or merge to master.
The proof-of-concept is configured to automatically build on push or merge to sethfischer:mkdocs.
Periodically project maintainers may receive notification from GitHub that dependencies in requirements.txt have a security release available. At a guess this would be a annual task that can be done by someone who has experience with pip.
does it support release versions?
Yes, Read the docs does support release versions which are based on tags.
I agree, versioning is important. I will look at the options and add it to the proof-of-concept.
To make use of versioning we may need to use the MkDocs readthedocs theme. The readthedocs theme is one of two MkDocs built-in themes so moving to that would remove a dependency.
are there any other changes we'd need to look at making to support this?
This is an experiment, the purpose of which is to identify any further changes that may be required. Over the next few months I'll regularly rebase sethfischer:mkdocs off nasa-jpl:master; noting any problems in the description of this issue.
This is really awesome and makes it easier to use for those new to GitHub. Great effort!
Investigation into hosting versioned MkDocs on GitHub Pages. This is a possible alternative to MkDocs hosted on readthedocs.
- Need to use the MkDocs Material theme. See https://github.com/nasa-jpl/open-source-rover/issues/317#issuecomment-1046182232 above for screenshot.
- Use mike which is a utility for deploying multiple versions of a MkDocs-powered docs to a Git branch.
Notes:
- Relative GitHub links would still need to be converted to absolute. This is due to GitHub Pages being served from
http(s)://<organization>.github.io/<repository>rather thanhttp(s)://github.com/<organization>/<repository>. - No automated deploy out-of-the-box. But this could possibly be added at a later date with a GitHub Action. Without a GitHub Action a maintainer will need to manually build the docs.
Comparison of hosting options: Read the Docs vs. GitHub Pages.
| Feature | Read the Docs | GitHub Pages |
|---|---|---|
| Automated deploy | Yes | Manual action for maintainer (or GitHub Action). |
| Domain example | https://<project>.readthedocs.io |
https://<organization>.github.io/<repository> |
| Theme | MkDocs Read the Docs | MkDocs Material |
| Versioned | Yes | Yes |
| Requires absolute links to GitHub files + folders | Yes | Yes |
| Configuration (one off) | Maintainer creates a RTD account and links it to GitHub. | Maintainer configures GitHub pages. |
| Dependencies | + mike + GitHub Action (optional) |
The GitHub Pages option will have a higher maintenance burden due to the additional dependency and GitHub action.
Thanks for the thorough analysis! I'm happy to help create the Github action if necessary, but if the options are otherwise equivalent in your opinion, I'm fine with read the docs. I do like that I don't need an account for read the docs though with the pages option.
I think I asked this already, but can you remind me why you couldn't get relative links to work? The readthedocs documentation and github pages documentation are pretty explicit in saying that it should work.
I forgot I set this up in the past already. This is my Github action:
name: docs
on:
push:
branches:
- "main"
workflow_dispatch:
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Build and push docs
uses: athackst/[email protected]
with:
publish_branch: gh-pages-main
edit_uri: edit/main
It uses MkDocs Simple Plugin and support relative links.
I think I asked this already, but can you remind me why you couldn't get relative links to work? The readthedocs documentation and github pages documentation are pretty explicit in saying that it should work.
@Achllle As you state, links between documentation pages can and should be relative.
By GitHub relative links I'm referring to links in the documentation that point to the GitHub app.
An example is #361. /electrical/pcb/ is a link to a GitHub app page, which is a directory listing.
They can be found in [the PCB folder](/electrical/pcb/)
On GitHub this resolves to: https://github.com/nasa-jpl/open-source-rover/tree/master/electrical/pcb In the built documentation this resolves to: https://osr-demo.readthedocs.io/electrical/pcb/ which does not exist[^1].
so the suggested change is:
They can be found in [the PCB folder](https://github.com/nasa-jpl/open-source-rover/tree/master/electrical/pcb).
[^1]: See the link the PCB folder on https://osr-demo.readthedocs.io/en/latest/electrical/index.html
I'm fine with read the docs. I do like that I don't need an account for read the docs though with the pages option.
@Achllle I think GitHub Pages is a good way to go. If you agree I will:
- Change the theme to MkDocs Material
- Add mike and do some local testing to ensure versioned documentation is working.
Both of the above are requirements for having versioned documentation hosted on GitHub Pages.
- Then I will hand over to a maintainer for deploying to GitHub Pages.
I see. It's odd to me that there's no out of the box support for this seemingly common scenario. I found https://github.com/mkdocs/mkdocs/issues/1619 which explains why it doesn't work.
To me, replacing relative links unfortunately is a show stopper. It means that someone browsing on a fork or commit will be taken away from that fork or commit without any warning. That can lead to confusion and waste of time. In addition, we support multiple versions of ROS and with the upcoming new rover design, we'll need even more pages. Finally, it means that we have to educate contributors that they need to use absolute links in some cases and relative links in others, which I don't love because it means increasing the barrier to contribution.
I wonder if it can be easily achieved with a macro or simple mkdocs plugin. Whenever a relative link to a non-page/non-image is detected, we replace it with an absolute link at generation time, so that we have the best of both worlds.
Unfortunately I can't see a solution to this. I have a few ideas but they very quickly snowball into quite big changes which will not meet the following requirements defined when the issue was opened:
- no changes to the directory structure of the project
- allow the documentation to be displayed/used as it currently is on GitHub.com
I agree with @Achllle in that we do not want to introduce any confusion in the documentation. Especially as builders are, and have been, very happy with the presentation of the current documentation.
As stated above, the justification of introducing built documentation was based on minimal changes to the project and no changes to the documentation workflow. We have now established this is not the case. If people are in agreement I suggest we close this issue and related pull requests.
I've reviewed comment 1279904259 above and also taken another look at jimporter/mike.
The choice of hosting platform comes down to the following pairings to support versioned documentation:
- If we want to host on Read the Docs we must use the theme MkDocs Read the Docs.
- If we want to host on GitHub pages we must use the theme MkDocs Material.
See earlier comments in this issue for screenshots of each. Other than that that all else will be equivalent.
No strong preference here. I like GitHub actions and can help set them up for automated deployments but I see that there's a dependency for it. ReadTheDocs is also frequently used so to me either are sound choices. I would pick what is easiest to maintain + explain to others such that it "just works".