Hello everybody,
there are currently a few technical issues with the documentation template and I see multiple ways to solve it. Specifically, the navigation bar of the JS Doc is broken, which is unfortunately a bug in the otherwise great readTheDocs template.
As I got told in this issue https://github.com/mkdocs/mkdocs/issues/2234 , the template used by readTheDocs allows in its navigation for only 2 levels of manual nesting, the deeper nested nav items have to evolve from headings in the MD file. For this reason, the current doc’s nav bar is so bugged. The navigation settings can be found here: https://github.com/aeternity/aepp-sdk-js/blob/develop/mkdocs.yml
For our current documentation this means we have three solutions:
- Change the theme.
With some colour adjustments, it could be decent enough to suit our needs:
Pros:
- we can nest topics as we need
- sleek modern design if colours are adjusted
Cons: We have to adjust the documentation template a little, as the member functions don’t automatically get their nav item seemingly (see nav) - the template seems a little more limited in its nesting capabilities, unfortunately, 4th level nestings are rendered like 1st level items when it’s parent is unfolded, at least for manually created nav items like
- Test:
- Test:
- Test:
- Test: api/ae/aens.md
havn’t checked with nav items generated from document structure.
- Flatten the documentation
We flatten the generated documentation (or at least the api reference part of it which nests quite deep) to one big file whose headings resemble a favourable nav automatically
Pros:
- We can keep the popular
readTheDocstheme - Nav bar items from documents nest very, very deep if necessary
- Partly flatten the documentation
We could flatten parts of the doc which tend to nest deep to bigger files, witch which we could resemble the nav structure, obeying the limitation from the issue cited above.
Pros: Keep the readTheDocs theme
Cons: It would require quite some configuration work to make the doc builder aware of this “plan”
What do you think about this, does anyone have another idea?
