Setup documentation Workflow

Documentation syntax, tools & workflows

14:10 Monday, December 13, 2021

I have been searching a lightweith, scablable and easy-to-use documentation method for around half a year since I finished my 150+ page-dissertation and wrote many other personal notes using Microsft Word. Previously, I searched and tried a few notetaking tools such as Roam, WorkFlowy, Evernote which didn't work out quite well for me. In fact, I sticked with Word and picked up OneNote, Notion, TheBrain to write notes, organize personal plans and projects. These tools works quite well for me at the beginning, but after I accumulated more data and records (e.g. seveal documents with 1000+ pages), Word and Notion begin to struggle with performance and scability issues. Additionally, word files and formats usually can't be coverted into html files in a straitforwad way, so another headache creeps in when I think about disseminating part of these written materials in my personal website on-line. I relize it is time to find an alternative.

Initially, I tried to write light-weight documents using Markdown(md). But they were not very appealing to me immediately, because I missed some key features like table of cotents, navigation structures offered by what-you-see-is-what-you-get applications(e.g. Microsoft Word). Nonetheless, later on, when I browsed many extensive long structured documents/manuals originally written in md for open source projects, I reallized it would be a good solution to my problem too. These documents could either be hosted on-line in Github or viewed locally, and they can also be compiled as HTML files to read and share.

So I fall back on md and start to learn these enabling tools for md documentation. At this moment, I am experimenting with some tools and trying to set up efficient workflows. For local documentation, I now decide to pick up Obsidian which I abodoned before. For on-line publication, I firstly try to use sphinx , it is not long before I find that MkDocs has similar functionalities but with more simpler md syntax and easier configuration. There is a more detailed article StructuredText vs. Markdown for technical documentation and reStructuredText 和 Markdown 该选谁？. In the following sections, I will share the most useful tips and workflows I have used so far.

Markdown vs reStructuredTExt

Markdown syntax is simple and widely used. By comparision, reStructuredTExt (rst) is more powerful and uniformed. Sadly, these two are not fully compatible. By now, as I am more familar and comforable with md, so I decide to use it to document my contents. But, considering of future demands, one day I may need to use more advanced features of rst, so I would most likely to write md documents in way that can be easily handled or reused by rst processers.

The list below shows some comparision between makrdown and reStructuredText

Markdown

Publish md documents on Github repository using MkDocs

With MkDocs, all the md documents can be viewed locally on your browser. More attractively, they can be easily pushed to your Github repository and to be viewly publicly on a website as manuals or blogs too. Actually all the contents of this website are initially witten in md, and then converted to HTML by MkDocs. How handy and fantastic it is!

To fully benefit from this feature, firstly create a repositrory on your github account and clone it into your local computer. Starting from the local folder magic can happen soon, and you just execute the following commands or follow the instructions from mkdocs.org:

* `mkdocs new .` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server, and view it at http://127.0.0.1:8000/ in your browser
* `mkdocs build` - Build the documentation site.
* `mkdocs gh-deploy` - upload your local documents to your remote repository on github and publish there.

As one of the drawbacks of md documents compared with reStructureText, the way to generate a table of content (TOC) is not uniformly specified in the syntax, so it is often problematic when you switch between md processing applications. Currently, mkdocs provides two different themes (i.e. ReadTheDocs and mkdocs), so that you can to arrange your pages in two distinct ways.

configure table of contents in readthedocs theme

Readthedocs theme, as the name implies, is designed for holding documents, therefore it can handle the structures of long and extensive documentions very well. To get a nice outline of your documents, by default, it will rely on the local folder and file structure. If you want to show the fiels in a differnt way, just add your customized TOC structure in the mkdocs.yml file.

configure table of contents in mkdocs theme

If you choose to use the mkdocs template, it will generate the navigation setions shown on top of your website home page using your local file hierarchy by default. This feature is nice and clear only if you have very limited amount of subsections, but it would be less informative if you have many different pages or sections to show. Likewisely, there is also a way to customize your website/file structure by edit the yml configuration file.

configure themes in mkdocs.yml

For the two built-in themes (mkdocs and readthedocs) that are currenlty supported by mkdocs, there are many other configurable options which can be added/edited in the mkdocs.yml file. Check the details here: choose your theme

In summary, MkDocs is a very convenienvet tool to deploy a simple website. It incorporates two useful themes to host either a documenation website or functional website. Nonetheless, if there is no automatic way to generate TOC, and it would be difficult to set up the hierarchial structure when you have a lot of md files.

Local documentation with Obsidian

When work on md files localy, I use Obsidian to process and manage them. TOC has a direc reflect of your directory struture within one vault, which is a term/method used by Obsidian to curate an independent and standalone repository. This feature is pretty neat enough if you learn to use folder structure and naming appropriately.

Two usefule tips:

- [[]] # internal link
- #tools #  the tag

To learn more instructions on how to use obsidian, check out at obsidian workflow .

Publish md documents on Github repository using Jekyll

Github Docs

reStructuredTExt

Publish reStructuredText on Github repository with Sphinx

TODOs: - add more instructions on how to use sphinx. - local editing of rst files. - publish on github. read the docs

after running the command below:

$ sphinx-quickstart

You can use Markdown using MyST and reStructuredText in the same Sphinx project. We support this natively on Read the Docs, and you can do it locally: pip install myst-parser

Then in your conf.py:

extensions = ['myst_parser']

host on github pages

To deploy the contents on Github pages, we just simply need to upload the local directories of build html fiels to the gh-pages branch. If you use mkdocs. The same function is implemented when you execute the mkdocs gh-page command, which actually employs another command called ghp-importunder the hook. But here, you can use the command ,

git push origin gh-page

host on readthedocs
tiel six

Workflow to update and publish docs

TODOs: add more instructions on how the workflow is like.