Documentation tutorial ¶
Our favorite document generator is sphinx and we use the reStructuredText markup and sphinx-design
I’m not impressed if you’re a good engineer. I’m impressed if you’re a good teammate.
https://fediverse.org/RandallKanna/status/1387202807103574016?s=20
Awsome Documentation news
Documentation
-
People
- Chris Holdgraph sphinx, executablebook
- Chris Sewell (MyST-Parser)
- Eric Holscher readthedocs
- Juan Luis (https://fediverse.org/juanluisback, sphinx, read the docs)
- Georg Brandl (The sphinx creator)
- Kevin Sheppard (sphinx material)
- Martin Donath (mkdocs material)
- Manuel Kaufmann (humitos, https://fediverse.org/reydelhumo sphinx, read the docs, sphinx-material)
- Paul Everitt (https://fediverse.org/paulweveritt, sphinx)
- Pradyun Gedam (sphinx furo)
- Takeshi Komiya (sphinx core)
-
Advices
- You are what you document (Monday, May 5, 2014)
- Doc
- 13 Things People Hate about Your Open Source Docs
- Beautiful docs
- Designing Great API Docs (11 Jan 2012)
- Docness
- Hacking distributed (february 2013)
- Jacob Kaplan-Moss (November 10, 2009)
- Agile documentation best practices
- Best Practices for Documenting Technical Procedures Melanie Seibert
- Plone
- Twilio
- TODO
-
Good docs
- Intro to Documentation with Sphinx and reStructuredText’s
- geopandas
- cakephp documentation
- Sphinx CDS ( Climate Data Store ) toolbox documentation
- Diátaxis Framework A systematic framework for technical documentation authoring by Daniele Procida
- Fastapi (from Sebastián Ramírez)
- Mattermost
-
poliastro - Astrodynamics in Python
- 1 All its documentation is written in Markdown using MyST (https://myst-parser.readthedocs.io) 🤯)
- 2. It has plenty of amazing math formulas nicely rendered using nbsphinx)
- 3. Gallery full of examples using “poliastro” itself created with “nbsphinx”)
- 4. INTERACTIVE 3D PLOTS WITH PLOTLY
- 5. Nice 404 Not Found pages using “sphinx-notfound-page”
- 6. Massive usage of tooltips via “sphinx-hoverxref” (https://sphinx-hoverxref.readthedocs.io) to not lose context while you are reading
- 7. Pretty nice split of pages following the concepts behind Diátaxis (https://diataxis.fr) to find out immediately what you are looking for! Split in these sections: Tutorials, How-To guides, Reference, Background, Links ✍️
- pretalx (Conference planning tool: CfP, scheduling, speaker management)
- ray
- Sfepy documentation
- Sphinx-material (by Kevin Sheppard)
- vsketch (for the API)
-
Document generators (sphinx, mkdocs, etc..)
- Sphinx documentation builder
- docutils (open-source text processing system for processing plaintext documentation )
- executablebooks (Build interactive, publication-quality documents from Jupyter Notebooks )
- jupyter-book (Build interactive, publication-quality documents from Jupyter Notebooks )
- bookdown
- Authorea
- Doxygen
- gatsby (Build blazing fast, modern apps and websites with React), graphQL Foundation member
- Hugo (The world’s fastest framework for building websites)
- Javadoc
- Jekyll
- JSDoc
- mdbook (Create book from markdown files. Like Gitbook but implemented in Rust)
- Mkdocs (mkdocs-material)
- Pandoc
- pdoc (Auto-generate API documentation for Python projects)
- redoc
- swagger-ui
- Hosting
- Formats
- Projects
-
Tools
- annotator (Image annotation for Elementary OS and Debian )
- VSCodium/ autodocstring
- Dash
- diagrams
- Diagrams (lets you draw the cloud system architecture in Python code)
- drawio (diagrams.net)
- flameshot (Powerful yet simple to use screenshot software)
- Graphviz
- jinja
- MySTyc : Online conversion from reStructuredText to MyST
- pygments (generic syntax highlighter)
- Zeal documentation browser
- Videos
- Wiki documentation