diff --git a/docs/source/conf.py b/docs/source/conf.py index 21bc5cf..73e0439 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,7 +15,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ - 'myst_parser', + # 'myst_parser', + 'sphinx_mdinclude', ] templates_path = ['_templates'] diff --git a/docs/source/index.rst b/docs/source/index.rst index e6fa637..8a6a71b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,16 +8,20 @@ Welcome to teamdocs's documentation! On this page you find the documentation for the GU Orbit software team. +The documentation contains information about: +- The Team +- The Goal +- The Projects +- The Development procedures - +.. mdinclude:: main.md .. toctree:: :maxdepth: 2 :caption: Table of contents: - - main.md - projects.md + projects/project_tree.rst + Indices and tables ================== diff --git a/docs/source/projects/project_tree.rst b/docs/source/projects/project_tree.rst new file mode 100644 index 0000000..034d0e4 --- /dev/null +++ b/docs/source/projects/project_tree.rst @@ -0,0 +1,31 @@ +Projects +======== +For more information see the projects documentation `Here `_ + +Information on how to create new project documentation can be found `Here `_ + +.. mdinclude:: projects_overview.md + +For more information see the project documentations below: + +.. _projects: + +.. toctree:: + :maxdepth: 2 + :caption: Table of contents: + + utilities/utilities_tree.rst + + +.. _project_documentation: + +.. toctree:: + :maxdepth: 2 + :caption: Table of contents: + + template/template_tree.rst + + + + + diff --git a/docs/source/projects.md b/docs/source/projects/projects_overview.md similarity index 91% rename from docs/source/projects.md rename to docs/source/projects/projects_overview.md index 7337305..e94c49c 100644 --- a/docs/source/projects.md +++ b/docs/source/projects/projects_overview.md @@ -1,5 +1,3 @@ -# GU Orbit Software projects - ## Utilities Library providing common functionality for GU Orbit Software projects, including: @@ -10,3 +8,4 @@ Library providing common functionality for GU Orbit Software projects, including |---|---|---| |[Utilities](https://github.com/guorbit/utilities)|[Docs](https://guorbit.github.io/utilities/)|[Wiki](https://github.com/guorbit/utilities/wiki)| + diff --git a/docs/source/projects/template/template_overview.md b/docs/source/projects/template/template_overview.md new file mode 100644 index 0000000..414cea0 --- /dev/null +++ b/docs/source/projects/template/template_overview.md @@ -0,0 +1,63 @@ +# Creating project documentation + +## Overview +It is important to document a project for multiple reasons: +- One it helps current people better understand the code base and practiceses used in the team +- But two also helps new people get up to speed with the project and the team + +## What to document +Anything really that you think is worth documenting. But here are some key points to look out for: +- How to setup, run the project(this usually included in the README.md of the project) +- How the team operates +- How to contribute to the project + - How code reviews are done + - How the team communicates + - How the team distributes work + - etc... +- Resources that the team uses + - Links to the tools used + - Links to the libraries/frameworks used + - Datasets used + - 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. + +The structure if these files is as follows: + +``` +Projects/ +|---project_tree.rst <--- Tree elements provide the navigation structure for the documentation discoverable by sphinx +|---project_overview.md <--- Overview of the page/project provides the information about the project +|---/ +| |---_overview.md <--- Overview of 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 + ``` + +You are good to go 🙂 diff --git a/docs/source/projects/template/template_tree.rst b/docs/source/projects/template/template_tree.rst new file mode 100644 index 0000000..705c434 --- /dev/null +++ b/docs/source/projects/template/template_tree.rst @@ -0,0 +1,2 @@ + +.. mdinclude:: template_overview.md \ No newline at end of file diff --git a/docs/source/projects/utilities/utilities_overview.md b/docs/source/projects/utilities/utilities_overview.md new file mode 100644 index 0000000..8959acc --- /dev/null +++ b/docs/source/projects/utilities/utilities_overview.md @@ -0,0 +1 @@ +# Utilities \ No newline at end of file diff --git a/docs/source/projects/utilities/utilities_tree.rst b/docs/source/projects/utilities/utilities_tree.rst new file mode 100644 index 0000000..3bb020f --- /dev/null +++ b/docs/source/projects/utilities/utilities_tree.rst @@ -0,0 +1 @@ +.. mdinclude:: utilities_overview.md \ No newline at end of file