Documentation for Python Accelerator Middle Layer.
The documentation follows the Diataxis approach.
- Clone the repository
- Create a virtual environment and activate it.
- Install the requirements with
pip install -r requirements.txt -r docs/requirements.txt. - Create a new branch. The main branch is protected so you can't push to it directly.
- Build the docs locally with
./build-docs.sh. The new version is available indocs/build/html/index.html. - When the local version looks good, push your changes and make a pull request. Pushes to main will build and deploy the new version.
For the notebooks it is necessary to have the required pyAML packages installed in the environment.
If you add a new dependency remember to also add it in the docs/requirements.txt or it will not be built correctly.
Content should be placed in these categories:
A tutorial is a practical activity where learning is done by doing something meaningful towards an achievable goal. The purpose is not to get something done but to help to learn. It should be structured as a lesson. The recommended format is to use a Jupyter notebook.
The tutorials are rendered using sphinx-gallery. They need to be written as a .py file using rst and not directly as Jupyter notebooks. You can use jupytext to make the workflow easier.
Jupytext can be used in the terminal but if you are using an IDE there are extensions available which makes it easier. In VS Code install Jupytext for Notebooks (congyiwu). You should then be able to right click on a .py file and choose Open as a Jupyter Notebook. You can run and modify the notebook as normal and the changes should happen in the .py automatically. Just remember that sphinx-gallery requires rst while notebooks use markdown so comments might not be rendered exactly the same.
To create a new tutorial you can start to write it as a notebook and then use the functionality to convert to .py. If you have written comments as markdown you need to manually convert them to rst.
How-to guides help to get something done in the correct and safe way. The focus should be on how to achieve a specific task.
Details of the difference between tutorials or how-to guides can be found at https://diataxis.fr/tutorials-how-to/#tutorials-how-to if you are unsure where to place your content.
Technical references are technical descriptions of the software, for example the API.
It is content where the user can look up information but is not meant to read everything.
Explanations have the purpose to deepen and broaden the understanding of a topic.
They provide background and context for why thing are done in a specific way, for example design decisions, technical constraints etc.
It can also contain details about alternatives and the reason why one specific alternative was chosen.