Docs

Here at GQC, we use 4 major documention tools for code documentation and other technical/dev documentation.

• Docs
  • Markdown Standards
    • Word To Markdown
    • Header for the markdown files
    • Types of Alerts
  • docusaurus
  • sphinx
    • readthedocs -- theme
  • nbdev
  • mkdocs-material

info

All these sites have support for search and digramming.

	Search	Mermaid.js diagrams
Docusaurus	Offline/local search for Docusaurus v2	Diagrams | Docusaurus
sphinx	Available out of the box	Mermaid for sphinx
nbdev	Available out of the box	Available out of the box
mkdocs-material	Available out of the box	Diagrams - Material for MkDocs

Markdown Standards

GQC uses a few extensions in VS Code to facilitate writing documentation in markdown:

• Markdown All in One (Yu Zhang)
• Markdown Paste (telesoho)
• Markdown Table (Takumi Ishii)
• markdownlint (David Anson)

Markdown Paste is useful for copying and pasting images into Markdown files. The easiest way to put images in a Markdown file is with this extension. To do so, simply:

1. Copy an image (however you can get it in your pasteboard)
2. Paste it into the document with ctrl+v or right click -> paste.
3. Rename the default filename (image.ext or image-n.ext).
4. Move the image file into a subdirectory images/
5. Update the filename link to prefix images/ directory

When renaming the default image names, it would be best practice to give the image a descriptive name, such as "btop_mem_usage.png". However, if you're working with a large number of image files, it might be easier to simply use a basic unique name. For example, you can rename all "image_n.png" files to the local markdown file's name. So for this document, called docs.md, we would have images at a location like images/docs_1.png

Word To Markdown

For creating a markdown page from a word document https://word2md.com/. This website will give you a starting point for your document.

1. It will give your document a Hierarchy based on your headers, however all Header 1 lines will be one # and that is earmarked for title in markdown. You can only have one of those in a document so you will need to modify the file.
2. It does not copy Images so you will have to handle that based on the section above.

Header for the markdown files

In each Markdown file the user needs to add in a header this should be put on Line 1 of the document.

---
last_update:
  date: 08/29/2024
  author: Deven, Jake, Melissa
tags: [nbdev, quarto, docusaurus, mkdocs, mkdocs-material, markdown, md]
---

Types of Alerts

note

note

tip

tip

info

important

info

info

caution

caution

danger

warning

docusaurus

Docusaurus is used for 3 major sites at GQC,

1. General
2. Projects
3. CCTV-docs

Docusaurus is an open-source documentation website generator. It is built by Meta (facebook) in React and is extremely powerful. It has support for mdx, diagramming, static search and much more.

sphinx

Sphinx is one of the most popular python packages for documentation. It is used for the python docs and the pandas docs.

It offers the functionality to generate documentation from docstrings in the code and with additional of extensions, you can create simple markdown files to create walkthroughs and have it show up in the documentation.

readthedocs -- theme

We mostly use the readthedocs themeIt uses a theme called sphinx-rtd-theme which

nbdev

nbdev is a python package that allows you to convert jupyter notebooks into python modules. It is used for the fastai library. The idea is to do your development entirely in Jupyter notebooks and nbdev handles the generation of py files, documentation, and tests.

mkdocs-material

mkdocs-material is a light weight, simple to use, and customizable static site generator that is used for the AI3 project documentation.