Improve API documentation #697
Conversation
Codecov Report
@@ Coverage Diff @@
## master #697 +/- ##
==========================================
- Coverage 95.26% 95.25% -0.01%
==========================================
Files 84 83 -1
Lines 8994 8985 -9
==========================================
- Hits 8568 8559 -9
Misses 426 426
Continue to review full report at Codecov.
|
|
This looks good to me. I'd say we should merge this in and then make additional PRs as we go through @jbeezley's checklist. Maybe I'm oblivious, but I don't see any point where we build the docs that show up on RTD. I also don't see the typical Sphinx makefile. Is someone manually running sphinx-build to update RTD? Should we have that as part of the CI? Do the API doc references from the docs rst files change with this change? |
|
The API docs are on gh-pages, which I update when I cut a release. We could automate it somehow with CI, but that's a separate issue. Getting the API docs on RTD is generally difficult. We would be better off just transitioning all the documentation over to markdown and integrating them with these. |
I am good with that moving away from rst. I am assuming that this jaguar creates markdown? I believe there tools to convert from rst to md. Should we create an issue for it? |
|
It doesn't create markdown, but it can ingest it. Jsdoc has a basic hook for rendering a readme as the front page of the documentation as well as a tutorials section. It's possible to do fancier things by modifying the templates. |
|
Great, thanks, having API docs out would be awesome. |
This switches from the default template to https://github.com/davidshimjs/jaguarjs-jsdoc. I had to make some bigger changes to the
utilsdirectory so that jsdoc could make sense of the structure. For most of the other classes, we will just have to make some minor changes to the jsdoc tags to make it work. I'll follow up on #448 with a checklist of things that should be done for each file to close the issue.