Merge pull request #1301 from TeamCOMPAS/update_docker_docs

Update docker docs

online-docs/Makefile

@@ -15,6 +15,10 @@ help:
 
 .PHONY: help Makefile
 
+linkcheck:
+	@$(SPHINXBUILD) -M linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

online-docs/README.rst

@@ -0,0 +1,63 @@
+COMPAS online documentation
+===========================
+
+- COMPAS homepage: https://compas.science/docs
+- Code documentation: https://compas.readthedocs.io/
+- COMPAS Github: https://github.com/TeamCOMPAS/COMPAS
+
+
+Tools
+-----
+
+- ReadTheDocs: https://readthedocs.org/
+- Sphinx: https://www.sphinx-doc.org/en/master/index.html
+
+Updating the documentation
+--------------------------
+
+1. Edit .rst files in 'docs/online-docs'
+2. Follow existing structure for new files
+3. Link new files to an index (toctree)
+
+
+Building the documentation locally
+----------------------------------
+
+In the repository root directory:
+
+.. code-block:: bash
+
+    pip install -e '.[dev]'
+    cd online-docs
+    make clean
+    make html
+
+
+
+
+View results in 'docs/online-docs/_build/html/index.html'
+
+Make sure there arnt any broken links! See the build logs:
+
+```
+(pages/User guide/docker: line   22) ok        https://stackoverflow.com/questions/23735149/what-is-the-difference-between-a-docker-image-and-a-container
+(pages/Developer guide/Developer build/docker-developer: line   23) ok        https://www.atlassian.com/continuous-delivery/principles/continuous-integration-vs-delivery-vs-deployment
+(pages/User guide/Running COMPAS/running-via-docker: line   41) broken    https://stackoverflow.com/questions/23735149/what-is-the-difference-between-a-docker-image-and-a-container#:~:text=An%20instance%20of%20an%20image,of%20layers%20as%20you%20describe.&text=You%20can%20see%20all%20your,an%20image%20is%20a%20container - Anchor '%3A~%3Atext%3DAn%20instance%20of%20an%20image%2Cof%20layers%20as%20you%20describe.%26text%3DYou%20can%20see%20all%20your%2Can%20image%20is%20a%20container' not found
+(pages/User guide/docker: line   49) ok        https://www.docker.com/
+
+```
+
+
+Pushing the changes online
+--------------------------
+
+1. Push updated (.rst) source files to COMPAS repo (not the _build dir)
+2. ReadTheDocs automatically rebuilds (takes up to 15 minutes)
+3. For manual rebuild:
+   - Log in to https://readthedocs.org/projects/compas/
+   - Go to 'Overview' page
+   - Click 'Build' button
+
+Note: If build fails with "environment" error, wait and retry.
+
+Logon details can be found on the COMPAS slack workspace (devel\_compas\_documentation channel).

online-docs/conf.py

@@ -51,6 +51,7 @@
     "sphinx.ext.viewcode",
     "sphinxarg.ext",
     "sphinx_tabs.tabs",
+    "sphinx_togglebutton",
 ]
 
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None),

online-docs/index.rst

@@ -24,13 +24,10 @@ Contents
 --------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 4
 
    ./pages/Getting started/getting-started
 
-   ./pages/User guide/user-guide
-   ./pages/Developer guide/developer-guide
-
     Code repository <https://github.com/TeamCOMPAS/COMPAS>
     Request an enhancement <https://github.com/TeamCOMPAS/COMPAS/issues/new>
     Report a problem <https://github.com/TeamCOMPAS/COMPAS/issues/new>
@@ -44,7 +41,18 @@ Contents
 
    ./pages/quick-links
 
-|
+.. toctree::
+   :maxdepth: 3
+
+   ./pages/User guide/user-guide
+
+
+.. toctree::
+   :maxdepth: 3
+
+   ./pages/Developer guide/developer-guide
+
+
 
 If you use COMPAS in the preparation of a publication, please :doc:`cite COMPAS <./pages/how-to-cite>`.
 

online-docs/pages/Developer guide/developer-guide.rst

@@ -5,8 +5,7 @@ TeamCOMPAS welcomes the active involvement of colleagues and others interested i
 the COMPAS software. We hope this Developer Guide helps anyone interested in contributing to the COMPAS software. We expect
 this guide to be a living document and improve along with the improvements made to the software.
 
-This guide covers the C++ COMPAS population synthesis code.  Post-processing code (Python scripts) are not (yet) covered
-by this guide.
+This guide covers the C++ COMPAS population synthesis code.
 
 
 .. toctree::
@@ -21,4 +20,4 @@ by this guide.
    ./changelog
    ./Programming style/programming-style
    ./Developer build/developer-building-compas
-
+   ./git-workflow.rst

online-docs/pages/Developer guide/git-workflow.rst

@@ -0,0 +1,32 @@
+Git Workflow
+============
+
+If you are not familiar with ``git``, please refer to a tutorial such as `this one <https://github.com/git-guides>`_.
+
+In ``COMPAS`` we work in the ``dev`` branch, and use the ``master`` branch for the major version changes. The main workflow is as follows:
+
+1. Create a git-issue describing the tasks you want to work on (this is optional, but recommended).
+2. Create a new branch from ``dev`` with a descriptive name (e.g. ``feature/issue-123``), and make a draft pull request to ``dev``. This will allow you to work on the code collaboratively and get feedback from the team.
+3. Make your changes, commit them, and push them to the remote repository. Every commit will trigger the continuous integration (CI) tests.
+4. Once you are happy with your changes, check that CI tests are passing, and switch the PR to ``ready for review``. This will make it clear to the team that your changes are ready for review.
+
+The team will review your changes, and may ask you to make some modifications. You can make these changes in the same branch, and push them to the remote repository. Once the changes are approved, the PR will be merged into ``dev``.
+
+CI Tests
+--------
+
+There are a few tests that are run automatically when you push your changes to the remote repository. These tests are:
+
+1. `spell-checking <https://github.com/TeamCOMPAS/COMPAS/blob/dev/.github/workflows/precommit-checks.yml>`_
+   This ensures that docstrings and comments are correctly spelled.
+2. `COMPAS compile test <https://github.com/TeamCOMPAS/COMPAS/blob/dev/.github/workflows/compas-compile-ci.yml>`_
+   This ensures that COMPAS C++ and python utilities can be correctly compiled (and COMPAS can run on a fiducial binary system).
+3. `COMPAS py-utils unit tests <https://github.com/TeamCOMPAS/COMPAS/blob/dev/.github/workflows/compas-compile-ci.yml>`_
+   This ensures that some of the python utilities are working as expected.
+
+
+The tests will fail if the fiducial binary system does not lead to a binary black hole merger.
+
+.. literalinclude:: ../../../py_tests/test_data/run.sh
+   :linenos:
+   :language: bash