Skip to content

Documentation

Jump to bottom
nh916 edited this page Jul 26, 2023 · 20 revisions

Documentation Guide

Suggestions

  • 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

Good Examples



Technologies Used

CI/CD

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

Files

  • 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

Running Docs Server Locally

To run mkdocs locally follow these steps:

  1. Clone the CRIPT Python SDK repository
  2. create and activate your virtual env
  3. install this repository
    • pip install -e .
  4. Install documentation dependencies
    • pip install -r requirements_docs.txt
  5. Start server
    1. in the terminal type: mkdocs serve
    2. which should show in the terminal that documentations server is running on http://127.0.0.1:8000/

CI/CD

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

Fixing Broken Links

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.

Link Tools

The tools that I have used in the past that were really helpful include:

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

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

Help

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.

CRIPT Platform | CRIPT Scripts | CRIPT Python SDK GitHub | CRIPT Python Package PyPI

Clone this wiki locally