-
Notifications
You must be signed in to change notification settings - Fork 5
Documentation
- Documentation should be concise as long walls of text creates bad UX.
- Language should be simple, explicit, and unmistakable.
- Documentation uses simple vocabulary to avoid confusion.
- Every page is consistent.
- Consistency makes finding information very easy and clean.
- The navigation should be easy to see.
- Long or wordy navigations makes it harder to navigate through.
- Sections should be clearly labeled as what they are
- It should not overwhelm the user with unnecessary information.
- There should be pictures, icons, and notes where available to walk the user through the software.
- User should find everything they need from a simple glance.
- Things that should get users attention should be get the users attention such as using Warning or other widgets.
- There should be bullet/numbered lists where possible as they are easy to glance and grasp.
- There should be simple code examples for the user to learn how to interact with the software.
- Variable names can sometimes be confusing for a first time user because they are unsure if
data_object
is functionality or just a plain variable we made up for the example.- Try to use my_data_object to show that it is just an example.
- Good grammar and punctuation are always nice, but not a big deal.
- Repetition is generally okay because it helps teach and reaffirms what the user knows.
- You know your documentation is good when you can easily refer to it whenever you or anyone else is lost and it quickly makes everything very clear.
- Good documentation should be up to date
- It would be bad if the documentation is giving the wrong advice and even worse would be if different sources are giving different information because the documentation is outdated.
- When describing nodes try to link to the page in the manual that has full text for the node and can give some more information
- Such as using the syntax of:
https://pubs.acs.org/doi/suppl/10.1021/acscentsci.3c00011/suppl_file/oc3c00011_si_001.pdf#page=<PAGE NUMBER>
- Try to always use named arguments in your code examples, so the user is able to clearly understand the code and what each value is for
- Have comments in code examples where applicable, to better explain the code and what could be confusing
- choose good clear self-documenting names for the code examples for the user to easily understand the code
- For documenting exceptions and errors please visit CRIPT Python SDK Exceptions wiki article
- Google has some of the best documentation.
- Atlassian BitBucket
- Django Documentation
- React Native Documentation
- Digital Ocean Django deployment documentation
- Java Docs can be good too.
numpy style docstring ideal order
This is generally the ideal order to put things for Numpy style docstrings.
- Short Summary
- Extended Summary
- Parameters
- Returns or Yields
- Other sections (Examples, Notes, References, etc.)
- Warns
- Raises
def add_numbers(a, b):
"""
Add two numbers together.
This is the extended summary section.
This function is a basic example to demonstrate the proper order
of NumPy-style docstrings. It takes two numbers, adds them, and returns the result.
Parameters
----------
a : float
The first number to add.
b : float
The second number to add.
Returns
-------
float
The sum of `a` and `b`.
Notes
-----
This is a simple addition function and may not handle edge cases.
Examples
--------
>>> add_numbers(1, 2)
3
>>> add_numbers(0.5, 0.5)
1.0
Warns
-----
UserWarning
If either of the numbers is very large, the result might not be accurate.
Raises
------
TypeError
If input arguments are not numbers.
"""
if not (isinstance(a, (int, float)) and isinstance(b, (int, float))):
raise TypeError("Both arguments should be numbers")
if abs(a) > 1e7 or abs(b) > 1e7:
import warnings
warnings.warn("Very large numbers detected. Result might not be accurate.", UserWarning)
return a + b
- The documentation for Python-SDK utilizes Material MKDocs.
The GitHub workflow file for building of the docs and pushing it to gh-pages can be found in .github/workflows/docs.yml, it largely comes from the Material MkDocs documentation regarding CI/CD
-
mkdocs.yml
- Contains settings, plugins, theme that is used throughout the documentation
- Contains the navigation for the whole documentation
-
requirements_docs.txt
- Contains all python packages needed for the documentation
- GitHub actions installs all requirements.txt whenever triggered
-
docs/
- Can contain documentation written in markdown and html
- Colors, icons, diagram, charts can be a helpful way of explaining concepts
- in majority of places it is
::: cript.nodes.primary_nodes.project
which means to get the documentation from the docstrings of that file
-
docs/stylesheets/extra.css
- Contains the css that every page has
To run mkdocs locally follow these steps:
- Clone the CRIPT Python SDK repository
- create and activate your virtual env
- install this repository
pip install -e .
- Install documentation dependencies
pip install -r requirements_docs.txt
- Start server
- in the terminal type:
mkdocs serve
- which should show in the terminal that documentations server is running on
http://127.0.0.1:8000/
- in the terminal type:
within .github/workflows/docs.yaml
is the workflow to build the documentation from docstrings within src/cript/ and MD files
then push to the built html and css to gh-pages branch.
The repository is configured to listen to the gh-pages branch for any pushes. Once there has been a push to gh-pages GitHub pages deploys deploys the new changes to the repositories GitHub pages URL
From past experience I've noticed that MkDocs is able to notify developers of some of the broken links, however, it is not able to find all the borken links especially if there are links within docstrings.
The tools that I have used in the past that were really helpful include:
-
screaming frog
- Web crawler mainly used for SEO and will also report broken links for us to fix
-
Xenu's Link Checker
- Older tool that can check the website quickly and report broken links
- YouTube Video Tutorial
Before running the crawlers locally on the documentation website, I'd recommend building the site and then serving it locally not bump into any issues regarding the documentation website breaking or being slow.
mkdocs build
Ideally, we'd want to check all broken links in CI and get a notification as soon as something breaks for us to fix, so there will never be a broken link in the documentation pages
-
Python Black Formatter Online Playground
- Feel free to use the Python Black formatter online live formatter, to format short snippets of code
If you bump into any issues while working with Material MkDocs documentation software, you have a few resources you can use. Firstly, can ask questions on this repository's discussion and someone from the CRIPT Python SDK team will try to help. You can also refer to Material MkDocs repository for expert help in Material MkDocs. They also have a discussions, Material MkDocs support methods, and gitter chat for live support.