diff --git a/docs/source/projects/template/template_overview.md b/docs/source/projects/template/template_overview.md index 414cea0..18838bd 100644 --- a/docs/source/projects/template/template_overview.md +++ b/docs/source/projects/template/template_overview.md @@ -21,9 +21,11 @@ Anything really that you think is worth documenting. But here are some key point - Papers that contributed to the work ## How to document -It is fearly simple to do this. -Most projects primarily rely on sphinx-autodoc to generate documentation from the docstrings in the codebase this is important to understand functions and objects, however for teams documentation we use markdown files. +It is fearly simple to do this. And it can be done in only a few steps. +1. Create a new folder in the `projects` folder. +Under that folder create a new markdown file called `_overview.md`. This file will contain the overview of the project. This is the file that will be displayed on the projects page. +Secondly create a new rst file called `_tree.rst`. This file will contain the navigation tree for the projects docs. The structure if these files is as follows: ``` @@ -32,32 +34,48 @@ Projects/ |---project_overview.md <--- Overview of the page/project provides the information about the project |---/ | |---_overview.md <--- Overview of the project +| |---_tree.rst <--- Navigation tree for the project | |---_.md <--- provides some other important information about the project, eg how the team operates ``` -So to start creating the teams documentation: -1. Create a new folder in the Projects folder -2. Create a new markdown file in the new folder called `_overview.md` -3. Add the following to the file: - ```markdown - # Overview - is a project that does other blah blah blah - ``` - -4. Add the following to the `_tree.rst` file: - ```rst - .. mdinclude:: /_overview.md - ``` - to include the markdown file you wrote the documentation in - -5. Add the following to the `index.rst` file: - ```rst - .. toctree:: - :maxdepth: 2 - :caption: Projects - - /_tree.rst - ``` +The `_tree.rst` file should contain the following: +```rst +.. mdinclude:: _overview.md +``` + +The `_overview.md` file should contain the following: +```markdown +# + + is a project that does other blah blah blah +``` + +2. Populate the projects brief description in the `_overview.md` file + +3. Populate the `_tree.rst` file with your projects rst file similarly: +```rst +.. _projects: + +.. toctree:: + :maxdepth: 2 + :caption: Projects: + + utilities/utilities_tree.rst + /_tree.rst + +``` You are good to go 🙂 + +### Local/Repository documentation +This documentation should only contain the following: +- How to setup the project (Readme.md) +- How to run the project (Readme.md) +- Autodoc (Sphinx, so all the functions and classes are documented) + +>**Note:** It is important to create docstrings for everything you write. This isn't just helpfor for other people but helps you as well when months later you forgot what that piece of code was. + +The autodoc pipeline is available the template repository, set for auto deploy on every push to the main branch. + +Code has to be documented the Sphinx documentation style.