Merge pull request #204 from winter-telescope/docs

Document install, contributing, usage
winter-telescope · Nov 22, 2022 · 721e7d3 · 721e7d3
2 parents 2345f60 + 91c9a59
commit 721e7d3
Show file tree

Hide file tree

Showing 57 changed files with 277 additions and 244 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -0,0 +1,35 @@
+Since _winterdrp_ is an open-source software project, *anyone* can contribute it. You simply need to create a fork of the repository, commit your changes, and then make a pull request.
+
+We have a few general guidelines that are helpful for keeping things organised:
+
+* *Use Github Pull Requests* We like to make sure that the code stays working. So if you are developing something, create a fork of the repo and open a branch. Develop away, and when you are ready, open a pull request. We can then review the code and approve the PR to merge your changes into the main codebase. 
+
+* *Use Github Issues* to coordinate your development. Whether you found a bug, you want to request an enhancement, or you're actively developing a new feature, Github Issues is a great place to keep everyone informed about what you're working on. Click on the label button to provide more info about your topic. Every time you make a relevant PR, remember to tag the issue (e.g `git commit -m 'progress on #12'`), and when you finish and issue you can close it with a commit too! (e.g `git commit -m 'Close #12`').
+
+* *Keep Github Actions Happy!* Github Actions runs all of our unit tests, to make sure you didn't break anything with your commit. You can see if the CI is happy by checking on the github page (look for the badge [![CI](https://github.com/winter-telescope/winterdrp/actions/workflows/continous_integration.yml/badge.svg)](https://github.com/winter-telescope/winterdrp/actions/workflows/continous_integration.yml), or a tick/cross next to your commit). If your commit failed, be sure to check the Github Actions website logs, to see exactly what went wrong.
+
+* *Keep Github Actions Busy!* Github Actions will only run unit tests if we make the unit tests first. When you add a new feature, you also need to add some unit tests so that we can ensure this feature continues to work in the future. Your tests should be saved in the `tests/` directory, and you can find plenty of examples there to copy. Coveralls.io checks how much of the code is covered by tests, and helps you see which lines still need to be covered. You can see all of this on the website: https://coveralls.io/repos/github/winter-telescope/winterdrp or a summary badge [![Coverage Status](https://coveralls.io/repos/github/winter-telescope/winterdrp/badge.svg?branch=main)](https://coveralls.io/github/winter-telescope/winterdrp?branch=main). If your commit adds a lot of new code but does not add unit tests, your commit will be tagged on github with a red cross to let you know that the code coverage is decreasing. If you want to know more about how to design unit tests, you can check out a guide [here](https://medium.com/swlh/introduction-to-unit-testing-in-python-using-unittest-framework-6faa06cc3ee1).
+
+* *Keep the code well-documented* When you write code, it is easier to understamd 'what' than 'why'. People are not mind-readers, and this includes your future self. This is where documentation helps. If you add doctstrings following the [standard python style](https://peps.python.org/pep-0287/), the code can be automatically converted to documentation.
+
+## Updating the documentation
+
+The documentation (generated primarily from docstrings) can be modified with the following command, executed from the docs directory:
+
+```bash
+sphinx-apidoc -o source/ ../winterdrp --module-first --force
+```
+
+## Checking the tests locally
+
+You can run the tests with:
+
+```TESTDATA_CHECK="True" python -m unittest discover tests/```
+
+This will check that the correct test data version is available, and then run all the tests.
+
+You can also check the code contained within the docstrings/documentation:
+
+```bash
+poetry run make -C docs/ doctest
+```
diff --git a/README.md b/README.md
@@ -6,12 +6,4 @@
 
 Open-source modular python package for astronomy image reduction.
 
-Check out our [documentation](https://winterdrp.readthedocs.io/en/latest/?badge=latest) to learn more.
-
-# Testing
-
-You can run the tests with:
-
-```TESTDATA_CHECK="True" python -m unittest tests/test_wirc_imsub_pipeline.py```
-
-This will check that the correct test data version is available, and then run all the tests.
+Check out our [documentation](https://winterdrp.readthedocs.io/en/latest/?badge=latest) to learn more.
diff --git a/docs/flowcharts/summer/_monitor.png b/docs/flowcharts/summer/_monitor.png
diff --git a/docs/flowcharts/summer/_monitor_2.png b/docs/flowcharts/summer/_monitor_2.png
diff --git a/docs/flowcharts/summer/default.png b/docs/flowcharts/summer/default.png
diff --git a/docs/flowcharts/summer/full.png b/docs/flowcharts/summer/full.png
diff --git a/docs/flowcharts/summer/imsub.png b/docs/flowcharts/summer/imsub.png
diff --git a/docs/flowcharts/summer/log.png b/docs/flowcharts/summer/log.png
diff --git a/docs/flowcharts/summer/postprocess.png b/docs/flowcharts/summer/postprocess.png
diff --git a/docs/flowcharts/summer/realtime.png b/docs/flowcharts/summer/realtime.png
diff --git a/docs/flowcharts/summer/simrealtime.png b/docs/flowcharts/summer/simrealtime.png
diff --git a/docs/flowcharts/summer/test.png b/docs/flowcharts/summer/test.png
diff --git a/docs/flowcharts/summer/test_imsub.png b/docs/flowcharts/summer/test_imsub.png
diff --git a/docs/flowcharts/summer/testlog.png b/docs/flowcharts/summer/testlog.png
diff --git a/docs/flowcharts/wirc/default.png b/docs/flowcharts/wirc/default.png
diff --git a/docs/flowcharts/wirc/imsub.png b/docs/flowcharts/wirc/imsub.png
diff --git a/docs/flowcharts/wirc/test.png b/docs/flowcharts/wirc/test.png
diff --git a/docs/flowcharts/wirc/test_imsub.png b/docs/flowcharts/wirc/test_imsub.png
diff --git a/docs/source/about.rst b/docs/source/about.rst
@@ -0,0 +1,4 @@
+About
+=====
+
+What is winterdrp? Good question!
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -4,8 +4,8 @@
 # -- Project information
 
 project = package_name
-copyright = '2022, Stein'
-author = 'Stein'
+copyright = '2022, Robert Stein'
+author = 'Robert Stein'
 
 release = __version__
 version = __version__
@@ -18,7 +18,8 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
-    "sphinx.ext.viewcode"
+    "sphinx.ext.viewcode",
+    "sphinx_mdinclude"
 ]
 
 intersphinx_mapping = {

diff --git a/docs/source/contributing-guide.rst b/docs/source/contributing-guide.rst
@@ -0,0 +1,4 @@
+Contributing Guide
+==================
+
+.. mdinclude:: ../../.github/CONTRIBUTING.md
diff --git a/docs/source/contributors.rst b/docs/source/contributors.rst
@@ -0,0 +1,16 @@
+Contributers
+============
+
+winterdrp was created by `Robert Stein <https://robertdstein.github.io/>`_ and
+`Viraj Karambelkar <https://github.com/virajkaram>`_. However, we didn't do it alone.
+
+Other people who contributed to the code include:
+
+* Sulekha Kishore
+
+We also made great use of existing software:
+
+* `source-extractor <https://www.astromatic.net/software/sextractor/>`_ (a.k.a sextractor)
+* `scamp <https://www.astromatic.net/software/scamp//>`_
+* `swarp <https://www.astromatic.net/software/swarp/>`_
+* `psfex <https://www.astromatic.net/software/psfex/>`_
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,25 +1,35 @@
 Welcome to the winterdrp documentation!
 =======================================
 
-Winterdrp is a modular, flexible, open-source code to reduce analyse astronomy images, built using python 3.11.
+Winterdrp is a modular, flexible, open-source code to reduce analyse astronomy images, built using python 3.10.
+It was created by `Robert Stein <https://robertdstein.github.io/>`_ and
+`Viraj Karambelkar <https://github.com/virajkaram>`_ (see everyone who contributed at :doc:`contributors`).
 
-Check out the :doc:`usage` section for further information, including
-how to :doc:`installation` the project.
-
-.. note::
-
-   This project is under active development.
+* How does winterdrp work? Check out :doc:`about`.
+* How can you install winterdrp? You can find instructions at :doc:`installation`.
+* How can you use winterdrp? Have a look at :doc:`usage`, where there is a guide with examples. Want to use winterdrp for your own telescope? Great! Have a look at our :doc:`contributing-guide`.
+* This also describes what to do if you find a bug or want to request a new feature.
+* What does x piece of winterdrp do? See the full documentation at :doc:`modules`.
 
 Contents
 --------
 
 .. toctree::
     :maxdepth: 2
 
+    about
     installation
     usage
+    contributors
+    contributing-guide
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 4
 
     modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -51,12 +51,12 @@ We again recommend using conda. Whether you need these dependencies depends on y
 Dependencies include:
 
 * `source-extractor <https://www.astromatic.net/software/sextractor/>`_ (a.k.a sextractor)
-* `scamp <https://www.astromatic.net/software/scamp//>`_
+* `scamp <https://www.astromatic.net/software/scamp/>`_
 * `swarp <https://www.astromatic.net/software/swarp/>`_
 * `psfex <https://www.astromatic.net/software/psfex/>`_
 * `postgreSQL <https://www.postgresql.org/download/>`_
 
-PostgreSQL is relatively straightfoward to install via the `official website <https://www.postgresql.org/download/>`_.
+PostgreSQL is relatively straightforward to install via the `official website <https://www.postgresql.org/download/>`_.
 The other packages might be more complicated, and will depend on your platform.
 
 astromatic software with apt-get (Linux only)
@@ -83,20 +83,3 @@ You can try installing things via conda:
     conda install -c conda-forge astromatic-source-extractor astromatic-scamp astromatic-swarp astromatic-psfex
 
 
-Configuring variables
----------------------
-
-winterdrp has several options for execution.
-You can pass some of these as arguments, but some e.g tokens or passwords are best included as environment variables.
-
-You can find a full list of variables in `env.example`:
-
-.. literalinclude:: ../../env.example
-
-You can set these variables in the command line:
-
-.. code-block:: bash
-
-    export RAW_DATA_DIR=/home/astronomer/rawdata
-
-
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -1,6 +1,25 @@
 Usage
 =====
 
+Configuring variables
+---------------------
+
+winterdrp has several options for execution.
+You can pass some of these as arguments, but some e.g tokens or passwords are best included as environment variables.
+
+You can find a full list of variables in `env.example`:
+
+.. literalinclude:: ../../env.example
+
+You can set these variables in the command line:
+
+.. code-block:: bash
+
+    export RAW_DATA_DIR=/home/astronomer/rawdata
+
+Running the code
+----------------
+
 You can execute winterdrp via the command line:
 
 .. code-block:: bash
@@ -21,3 +40,4 @@ Alternatively, you can check via the code:
     >>> from winterdrp.pipelines import Pipeline
     >>> print([x for x in Pipeline.pipelines.keys()])
     ['wirc', 'summer']
+
diff --git a/docs/source/winterdrp.catalog.kowalski.rst b/docs/source/winterdrp.catalog.kowalski.rst
@@ -1,6 +1,11 @@
 winterdrp.catalog.kowalski package
 ==================================
 
+.. automodule:: winterdrp.catalog.kowalski
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
@@ -19,11 +24,3 @@ winterdrp.catalog.kowalski.tmass module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: winterdrp.catalog.kowalski
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/winterdrp.catalog.rst b/docs/source/winterdrp.catalog.rst
@@ -1,6 +1,11 @@
 winterdrp.catalog package
 =========================
 
+.. automodule:: winterdrp.catalog
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Subpackages
 -----------
 
@@ -51,11 +56,3 @@ winterdrp.catalog.skymapper module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: winterdrp.catalog
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/winterdrp.downloader.rst b/docs/source/winterdrp.downloader.rst
@@ -1,6 +1,11 @@
 winterdrp.downloader package
 ============================
 
+.. automodule:: winterdrp.downloader
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
@@ -19,11 +24,3 @@ winterdrp.downloader.get\_test\_data module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: winterdrp.downloader
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/winterdrp.errors.rst b/docs/source/winterdrp.errors.rst
@@ -1,6 +1,11 @@
 winterdrp.errors package
 ========================
 
+.. automodule:: winterdrp.errors
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
@@ -27,11 +32,3 @@ winterdrp.errors.exceptions module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: winterdrp.errors
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/winterdrp.monitor.rst b/docs/source/winterdrp.monitor.rst
@@ -1,6 +1,11 @@
 winterdrp.monitor package
 =========================
 
+.. automodule:: winterdrp.monitor
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
@@ -11,11 +16,3 @@ winterdrp.monitor.base\_monitor module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: winterdrp.monitor
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/winterdrp.pipelines.rst b/docs/source/winterdrp.pipelines.rst
@@ -1,6 +1,11 @@
 winterdrp.pipelines package
 ===========================
 
+.. automodule:: winterdrp.pipelines
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Subpackages
 -----------
 
@@ -20,11 +25,3 @@ winterdrp.pipelines.base\_pipeline module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: winterdrp.pipelines
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/winterdrp.pipelines.summer.config.rst b/docs/source/winterdrp.pipelines.summer.config.rst
@@ -1,6 +1,11 @@
 winterdrp.pipelines.summer.config package
 =========================================
 
+.. automodule:: winterdrp.pipelines.summer.config
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Subpackages
 -----------
 
@@ -19,11 +24,3 @@ winterdrp.pipelines.summer.config.constants module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: winterdrp.pipelines.summer.config
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/winterdrp.pipelines.summer.config.schema.rst b/docs/source/winterdrp.pipelines.summer.config.schema.rst
@@ -1,9 +1,6 @@
 winterdrp.pipelines.summer.config.schema package
 ================================================
 
-Module contents
----------------
-
 .. automodule:: winterdrp.pipelines.summer.config.schema
    :members:
    :undoc-members: