New documentation plan for Nunaliit

[ahayes]

The one big wiki doc for Atlas Builder documentation is handy for finding terms using the browser's search function, but sometimes takes too long for github to render, resulting in a timeout error.

I would like to identify a plan for migrating the documentation into some other form. I will use this issue to collect and track hopes, dreams, and options.

Currently, I have the following goals to balance:

• Simple syntax
• Easy to contribute
• Versioned and aligned with source repo
• Able to be included in pull requests alongside the code
• Possible to generate functional and attractive doc artifacts in other formats (PDF, ePub, HTML, etc.)

Any other goals to strive for?

Some things to investigate include:

• reStructuredText format (.rst) https://docutils.sourceforge.io/rst.html
• Sphinx doc generator - uses .rst as source to create HTML, PDF, and others https://www.sphinx-doc.org/en/master/
• mkDocs - uses Markdown files to generate static HTML docs https://www.mkdocs.org/
• VuePress - uses Markdown files and Vue templates to generate an HTML single page app for docs https://vuepress.vuejs.org/
• SlateDocs - Interactive API documentation builder https://slatedocs.github.io/slate/#introduction
• DocBooks - Yucky SGML/XML, but it is what PostgreSQL uses and the resulting documentation site is great. Not sure what tool they use to generate the site. https://docbook.org/ and https://www.postgresql.org/docs/current/
• Pandoc - converts doc formats (including markdown to docbook) https://pandoc.org/
• CommonMark - An attempt to create a well defined and portable Markdown syntax https://commonmark.org/

[Noznoc]

My only suggestion that isn't covered from your list is RMarkdown or RBookdown - Uses markdown and you can knit it into HTML, PDF, and more afterwards. I used it a lot for documentation and quick simple websites. You have to run it with R, but it doesn't really depend on R programming knowledge.

I am somewhat familiar with Sphinx but found it a bit complicated at first to use (even with programming experience).

[ahayes]

Was just editing something in the Atlas Builder docs and decided to try pandoc to convert our existing HTML + github markdown docs to PDF for kicks. Had to sudo apt install pandoc texlive-latex-base texlive-latex-recommended texlive-fonts-recommended on an ubuntu 18.04 development system, stick the wiki page contents in a file I named wiki_atlas_builder.github and then was able to run pandoc --from=html --to=latex --output=Nunaliit_Atlas_Builder_Docs_2022-03-23.pdf wiki_atlas_builder.github to generate Nunaliit_Atlas_Builder_Docs_2022-03-23.pdf

Only took a few minutes total and pandoc can be used to convert between myriad formats. So getting the existing docs into something else should be quite straightforward. I'm leaning towards ReStructuredText for the source but could be persuaded to try other simple formats like CommonMark. Then we can output all kinds of doc versions like DocBook, HTML, PDF, etc.

[alexgao1]

https://docs.gitbook.com
Looking at their criteria, there would need to be some changes to the repo.