Documentation Formatting Discussion

[keck-in-space]

Hello,

I was discussing some possibly out-of-order pages on the Math Component tutorial in this issue: fprime-community/fprime-tutorial-math-component#27. One of the comments on this issue mentioned that it is also hard to tell where you are in the tutorial and to navigate between other pages.

We typically use mkdocs with the mkdocs-material theme for internal documentation, which fixes the "where am I?" issue. So, I took a stab at rendering the docs with the navigation fixes using these tools.

Here's the rendered page if you want to see what it looks like: https://keck-in-space.github.io/fprime-tutorial-math-component/

Mkdocs also adds search, dark mode (optional), and a TOC for each page.

I am opening a discussion here to see if there is any interest in moving more pages to this format with these features, or if there are other possible documentation renderers that we would like to explore.

Thanks to @bocchino and @thomas-bc for the comments on the original issue.

[LeStarch]

We are currently reviewing all our documentation, so the timing of this is perfect! We've asked @cgcruz0304 to take a look at the result of the above render and pull that into the review!

[cgcruz0304]

This looks great!!

This is a cool search bar, it’s great how the results provide some context which will help users decide on which result to commit to viewing. I am wondering if we can set some limits to how much context a search result may reveal, that way each result during live search is displayed in a similar size.

For reference, the following is a screenshot of a result with varying levels of context.

[cgcruz0304]

I love how on the right there’s the navigation to different pages and another on the right where there’s navigation within the page. A big step up! I am wondering if a table of contents would be needed in the main content portion of the page if it is already shown on the right.

[keck-in-space]

I had a similar thought about the table of contents on the Welcome page, but since this was just a quick demo, I tried not to edit any existing pages.

There are many tunable parameters in the mkdocs.yml file on the repo that this builds from, here: https://github.com/keck-in-space/fprime-tutorial-math-component/blob/main/mkdocs.yml You can see I set a few custom options for how the site is rendered.

For the search settings, there are a few tunable options here, though I don't see much for configuring how much context is revealed per page. https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/

In general the docs for the mkdocs material theme are quite good. There are a few features that are locked behind becoming a sponsor, but nothing major that I've ever needed.

[keck-in-space]

Another thing I really like is that the code blocks can be easily copied by clicking the icon on the right side.

[thomas-bc]

@keck-in-space do you know if mkdocs (or any other tool) is able to help with versioning documentation? Currently we manually take snapshot of our documentation and expose those snapshots in our docs branch. Do you know of frameworks/engines that can help with this process?

[davidskeck]

Popping in on my personal account really quick -- You can do versioning with mkdocs-material theme with a plugin called mike. The docs for that are here: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/

Here's an example of mkdocs with versioning: https://squidfunk.github.io/mkdocs-material-example-versioning/0.3/
Click the version on the top left to change which version you're viewing.

The other tool I've seen used for this is Read the Docs, though I have not used it. The Zephyr project does use it and you can switch between versions using the dropdown on the bottom left. https://docs.zephyrproject.org/latest/index.html

I believe Read the Docs charges a monthly fee and isn't self-hosted/hosted on GitHub pages though.

[SterlingPeet]

@thomas-bc, I don't have documentation projects as big or formal as the F Prime docs, but I have had good luck using bump-my-version for making sure the version numbers all end up where they need to be. I find that to be the most challenging aspect, most of the rest of my release processes look like simple scripts with little to no branching.