Merge pull request #197 from CITCOM-project/dev_docs

Dev docs

Author: christopher-wild

docs/source/dev/actions_and_webhooks.rst

@@ -0,0 +1,26 @@
+Github Actions and Webhooks
+===========================
+
+Github Actions
+--------------
+
+Currently this project makes use of 3 `Github Actions <https://github.com/features/actions>`_, which can be found in the `.github/workflows <https://github.com/CITCOM-project/CausalTestingFramework/tree/main/.github/workflows>`_ directory
+
+They are:
+
+#.  ci-tests.yaml, which runs CI tests on each PR
+
+#.  lint-format.yaml, runs linting on each PR
+
+#.  publish-to-pypi.yaml, runs when a new version tag is pushed and publishes that tag version to pypi
+
+Github Webhooks
+---------------
+
+The project also uses 3 `Webhooks <https://docs.github.com/en/webhooks-and-events/webhooks/about-webhooks>`_, which can be found in the `project settings <https://github.com/CITCOM-project/CausalTestingFramework/settings>`_ on Github
+
+#.  To codacy
+
+#.  To codecov
+
+#.  To readthedocs

docs/source/dev/documentation.rst

@@ -0,0 +1,61 @@
+Project Documentation
+=====================
+
+This page aims to describe:
+
+#. The projects documentation style
+
+#. The tools used for documentation
+
+#. ReadTheDocs where the documentation for this project is hosted
+
+
+Documentation Style
+-------------------
+
+The `Sphinx docstring format <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#the-sphinx-docstring-format>`_ is used throughout the projects codebase to allow for the easy understanding of classes, methods, functions, etc.
+This format allows for the easy generation of html documentation pages.
+
+Checks for docstrings have been added to the projects Pylint configuration.
+
+Documentation Tools
+-------------------
+
+To install the packages required to work with the documentation please ensure the projects **dev** dependencies are installed::
+
+    pip install causal-testing-framework[dev]
+
+Sphinx
+******
+
+This project makes use of `Sphinx <https://www.sphinx-doc.org/en/master/>`_, to generate documentation.
+
+The documentation for the project sits within the `docs/` directory inside the project root.
+
+To manually build the docs, first navigate to the `docs/` directory and run::
+
+    make html
+
+This will populate `docs/build/` with static html pages containing the docs.
+To cleanup the compiled docs you can run::
+
+    make clean
+
+
+Situation within `docs/source` are the reStructuredText files (.rst) which contain the handwritten doc pages, which get compiled by the make commands.
+
+Autodoc & Autoapi
+*****************
+
+`Autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ is an extension to sphinx that can import code modules and compile documentation from their docstrings.
+
+`AutoAPI <https://sphinx-autoapi.readthedocs.io/en/latest/>`_ is a third party sphinx tool for recursively discovering code modules and compiling them into a logical doctree structure
+
+The configuration for Sphinx, Autodoc and AutoAPI are all found in `/docs/source/conf.py <https://github.com/CITCOM-project/CausalTestingFramework/blob/main/docs/source/conf.py>`_.
+
+ReadTheDocs
+-----------
+`Read the Docs <https://readthedocs.org/>`_ is a documentation hosting site that hosts, versions and builds documentation for free for open source projects.
+
+This project makes use of a Github Webook to trigger the build in ReadTheDocs, further reading on this can be found :doc:`here <../dev/actions_and_webhooks>`\
+

docs/source/index.rst

@@ -54,6 +54,8 @@ system-under-test that is expected to cause a change to some output(s).
    :caption: Development Documentation
 
    /dev/version_release
+   /dev/documentation
+   /dev/actions_and_webhooks
 
 Indices and tables
 ==================