Your feedback needed: Documentation Design

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:

  1. 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.

  1. 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 readTheDocs theme
  • Nav bar items from documents nest very, very deep if necessary
  1. 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?

5 Likes

The structure ,UI and writing of the documents is good enough for me, nice work!

I(maybe we) need more examples in detail :smiley:

2 Likes

The examples are coming - it’s important to have a clean UI though, so what do you guys think ?

2 Likes