Below we'll keep a semi-updated list of resources that we've found useful in writing and improving our own documentation. If you've got a suggestion for something else to add, please add it as a comment on our github issue on this here.
Table of Contents
- Getting involved
- Documentation tools
- Guides and articles on technical communication
- Events and resources for holding events
First things first, you need to have a project before you can make documentation. Below are a couple of resources on both finding projects as a new user, and helping users contribute to documentation if you manage a project:
These cover tools and software that are useful in documentation. If you have a suggestion for a new tool, add a comment here.
numpydoc is a set of extension for sphinx initially used by the numpy project and now more widely used in the scientific ecosystem. Among other features, it provides extra sphinx directives, and understands the numpy docstring syntax. This allows you to quickly build websites for your project.
Sphinxcontrib-napoleon is a set of extensions for Sphinx which understand both NumPy and Google style docstrings.
Doctr is meant to simplify the deployment of documentation from Travis-CI to GitHub pages, by providing a single tool to setup, build and deploy documentation builds.
It is an alternative to readthedocs, which is sometimes difficult in getting dependencies installed.
Doctr is still young and could have many features contributed, maybe by you!
Sphinx Gallery is a Sphinx extension that will automatically generate a gallery from a repository of examples that generate matplotlib plots. It also auto-generates a jupyter notebook that can be downloaded from the html page in the docs.
Sphinx Gallery automatically makes all identifiers present in every code block link to their definition. In conjunction with [intersphinx] this is allows seamless navigation between related projects.
custom_inherit is a Python package that provides convenient, light-weight tools for inheriting/merging docstrings in customizeable ways. This helps facilitate thorough and consistent documentation - documentation need not be duplicated manually when docstring sections are being inherited.
It provides both a decorator and a metaclass for facilitating docstring inheritance/merging. Numpy, Google, & reST docstring styles are supported out of the box.
The following tools fall under the category of "Documentation portals" they attempt to gather documentation from several sources in a coherent, uniform and searchable portal.
It does not have a concept of "next/previous" pages so is not meant for read-through tutorials.
Dash is a similar project. It is (for now) available for MacOS only, as native application. You can use it to get online resources, but is mostly meant to work off-line.
PyDoc fills again a similar niche. PyDoc first version were made public at end of 2016. Unlike the two above, PyDoc is meant to be Python only, and has no intent to be available off-line. Its tight integration with Python should allows it to automatically build api only docs for all Python project on PyPI and Warehouse.
Miscellaneous documentation tools
Docrepr extend the concept of MimeBundle that can be found in IPython and Jupyter to extend it to python's docstring. Using docrepr, the Jupyter Notebook and Spyder can show docstring of interactive object using rich html.
thebe test is a prototype to make example written using sphinx interactive and backed by an actual running kernel. Either running on a temporary server in the cloud (like SymPy documentation console), or even cnnecting to a locally running jupyter notebook server.
- BoostBook and QuickBook
- Breathe for connecting Sphinx and Doxygen
- cldoc — clang-based documentation generator
These are resources for communicating clearly, particularly about technical matters. If you have a suggestion for a new resource, add a comment here
- Modern Physics' Guide to Writing Well - https://drive.google.com/file/d/0B8VZ4vaOYWZ3ZDJzcWNWVUFFR00/view?usp=sharing
There are also many events that follow the same principles as the Docathon. We've compiled a list of them below. If you have a new event to suggest, post a comment here
Hackathon Events / Orgs
Documentation Events / Orgs
- Write the Docs (they also have a "writing day" event, here is a link to their projects page)
- The Open News Code Convening for docs on OSS
- Open Stack doc day here and here
- Atlassian documentation day