Publish documentation #17
Comments
lucaswerkmeister
added
the
documentation
|
I think for versioning the docs, I like the Flask/Pallets approach of always having the version number in the URL, and having a banner (stickied to the top of the screen) when you’re looking at older versions, pointing at the latest one. I think I don’t want to have “latest” URLs whose content changes with each release, except maybe as a redirect. (But if I change my mind on this, it’s always possible to add these URLs later.) |
|
Also, it would be nice to automatically update the documentation via GitHub action for each release – but I don’t think I want to block the 1.0 release on implementing that. I can live with manually pushing documentation updates for a while. |
|
As for where to host the docs, GitHub pages should work fine for now. If we want to move the docs, the established solution for redirecting from GitHub pages to elsewhere seems to be to have GitHub pages serve HTML with |
Sadly, the config file needs to be JSON – ESLint would also understand a CommonJS file, but a .js file would be interpreted as an ESM file due to our package.json type, and if it’s renamed to .cjs then ESLint tries to load it as JSON again. (It looks like the future JSDoc 5 might fix this and also add a default config path.) Part of #17.
Configure JSDoc. Sadly, the config file needs to be JSON – ESLint would also understand a CommonJS file, but a .js file would be interpreted as an ESM file due to our package.json type, and if it’s renamed to .cjs then ESLint tries to load it as JSON again. (It looks like the future JSDoc 5 might fix this and also add a default config path.) The layout.tmpl is based on JSDoc’s default template, but with a comment block added indicating where the warning about an old version will go. And since we have to copy over the file anyways, that’s also an opportunity to improve a few other things: change the title prefix from “JSDoc” to “m3api”, and defer the scripts. In the release workflow, we add a job to add the docs of the new release to the gh-pages branch, and to also update all previous releases to point to the latest release. (We actually do it the other way around: it’s easier to first update all docs and only then add the new ones.) The initial setup of the gh-pages branch will be done manually. Note that I don’t plan to rebuild old documentation: we just keep the same files in the Git history, updating them every time. If that doesn’t work out, we can still change it later. Implements #17.
According to its documentation, JSDoc is supposed to pick up a file called README.md by default, but evidently it didn’t. The parsed Markdown output looks pretty good – the only problem I’ve found so far is that the relative section links don’t work, which I think is acceptable. Part of #17.
|
It works \o/ https://lucaswerkmeister.github.io/m3api/ |
So far, the two levels of documentation are “read the README” and “read the code”. We should have an in-between step of publishing the jsdoc-rendered code documentation somewhere, ideally for each release.
The text was updated successfully, but these errors were encountered: