adds template

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']

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
 ==================

docs/source/projects/project_tree.rst

@@ -0,0 +1,31 @@
+Projects
+========
+For more information see the projects documentation `Here <projects_>`_
+
+Information on how to create new project documentation can be found `Here <project_documentation_>`_
+
+.. 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
+
+
+
+
+

docs/source/projects.md → 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)|
 
+

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
+|---<project>/
+|   |---<project>_overview.md <--- Overview of the project
+|   |---<project>_<somepart>.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 `<project>_overview.md`
+3. Add the following to the file:
+    ```markdown
+    # <Project> Overview
+    <Project> is a project that does <some description of the project> other blah blah blah
+    ```
+
+4. Add the following to the `<project>_tree.rst` file:
+    ```rst
+    .. mdinclude:: <project_folder>/<project>_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
+
+       <project_folder>/<project>_tree.rst
+    ```
+
+You are good to go 🙂

docs/source/projects/template/template_tree.rst

@@ -0,0 +1,2 @@
+
+.. mdinclude:: template_overview.md

docs/source/projects/utilities/utilities_overview.md

@@ -0,0 +1 @@
+# Utilities

docs/source/projects/utilities/utilities_tree.rst

@@ -0,0 +1 @@
+.. mdinclude:: utilities_overview.md