Merge pull request #126 from cositools/docs

Sphinx documentation

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: docs
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: |
+          sudo apt install pandoc
+          pip install sphinx sphinx_rtd_theme nbsphinx mock
+      - name: Sphinx build
+        run: |
+          make -C docs html
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/docs' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html
+          force_orphan: true
+

README.md

@@ -1,26 +1,10 @@
 # cosipy
-The COSI high-level data analysis tools
 
-## Installation from source
+The cosipy library is [COSI](https://cosi.ssl.berkeley.edu)'s high-level analysis software.
 
-Meant for developers. Currently the only option.
+The main repository is hosted in https://github.com/cositools/cosipy
 
-1. Clone the repository into your local machine
+For the cosipy installation and usage instructions please refer to the main [cosipy documentation](https://cositools.github.io/cosipy/).
 
-```
-git clone [email protected]:cositools/cosipy.git
-```
 
-2. Move to the cosipy folder
 
-```
-cd cosipy
-```
-
-3. Create a new conda environment. Optional but highly encouranged.
-
-4. Install it:
-
-```
-pip install -e .
-```

cosipy/response/FullDetectorResponse.py

@@ -835,7 +835,7 @@ def get_point_source_response(self,
             Effective time spent by the source at each pixel location in spacecraft coordinates
         coord : :py:class:`astropy.coordinates.SkyCoord`
             Source coordinate
-        scatt_map : :py:cass:`SpacecraftAttitudeMap`
+        scatt_map : :py:class:`SpacecraftAttitudeMap`
             Spacecraft attitude map
         
         Returns

cosipy/threeml/COSILike.py

@@ -34,34 +34,33 @@
 logger = logging.getLogger(__name__)
 
 class COSILike(PluginPrototype):
-
+    """
+    COSI 3ML plugin.
+
+    Parameters
+    ----------
+    name : str
+        Plugin name e.g. "cosi". Needs to have a distinct name with respect to other plugins in the same analysis
+    dr : str
+        Path to full detector response
+    data : histpy.Histogram
+        Binned data. Note: Eventually this should be a cosipy data class
+    bkg : histpy.Histogram
+        Binned background model. Note: Eventually this should be a cosipy data class
+    sc_orientation : cosipy.spacecraftfile.SpacecraftFile
+        Contains the information of the orientation: timestamps (astropy.Time) and attitudes (scoord.Attitude) that describe
+        the spacecraft for the duration of the data included in the analysis
+    nuisance_param : astromodels.core.parameter.Parameter, optional
+        Background parameter
+    coordsys : str, optional
+        Coordinate system ('galactic' or 'spacecraftframe') to perform fit in, which should match coordinate system of data 
+        and background. This only needs to be specified if the binned data and background do not have a coordinate system 
+        attached to them
+    precomputed_psr_file : str, optional
+        Full path to precomputed point source response in Galactic coordinates
+    """
     def __init__(self, name, dr, data, bkg, sc_orientation, 
                  nuisance_param=None, coordsys=None, precomputed_psr_file=None, **kwargs):
-        """
-        COSI 3ML plugin.
-        
-        Parameters
-        ----------
-        name : str
-            Plugin name e.g. "cosi". Needs to have a distinct name with respect to other plugins in the same analysis
-        dr : str
-            Path to full detector response
-        data : histpy.Histogram
-            Binned data. Note: Eventually this should be a cosipy data class
-        bkg : histpy.Histogram
-            Binned background model. Note: Eventually this should be a cosipy data class
-        sc_orientation : cosipy.spacecraftfile.SpacecraftFile
-            Contains the information of the orientation: timestamps (astropy.Time) and attitudes (scoord.Attitude) that describe
-            the spacecraft for the duration of the data included in the analysis
-        nuisance_param : astromodels.core.parameter.Parameter, optional
-            Background parameter
-        coordsys : str, optional
-            Coordinate system ('galactic' or 'spacecraftframe') to perform fit in, which should match coordinate system of data 
-            and background. This only needs to be specified if the binned data and background do not have a coordinate system 
-            attached to them
-        precomputed_psr_file : str, optional
-            Full path to precomputed point source response in Galactic coordinates
-        """
 
         # create the hash for the nuisance parameters. We have none for now.
         self._nuisance_parameters = collections.OrderedDict()

docs/api/data_io.rst

@@ -0,0 +1,8 @@
+Data IO
+=======
+
+.. automodule:: cosipy.data_io
+   :imported-members:
+   :members:
+   :undoc-members:
+

docs/api/image_deconvolution.rst

@@ -0,0 +1,7 @@
+Image deconvolution
+===================
+
+.. automodule:: cosipy.image_deconvolution
+   :imported-members:
+   :members:
+   :undoc-members:

docs/api/index.rst

@@ -1,9 +1,23 @@
 API
 ===
 
+This is cosipy's Application Programming Interface (API). It is an exhaustive list of all available classes and their properties, as well as the inputs and outputs of each method.
+
+If you are instead interested in an overview on how to use cosipy, see out `tutorial series instead <../tutorials/index.html>`_.
+
+.. warning::
+    Under construction. The description of some methods is still missing. If you need the description of a particular class, please open an `issue <https://github.com/cositools/cosipy/issues>`_ so we can prioritize it.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    response
-   coordinates
+   data_io
+   spacecraftfile
+   threeml
+   ts_map
+   image_deconvolution
+
+
+

docs/api/spacecraftfile.rst

@@ -0,0 +1,9 @@
+Spacecraft File
+===============
+
+.. automodule:: cosipy.spacecraftfile
+   :imported-members:
+   :members:
+   :undoc-members:
+
+

docs/api/threeml.rst

@@ -0,0 +1,10 @@
+COSILike (3ML plugin)
+=====================
+
+ThreeML plugin
+
+.. automodule:: cosipy.threeml
+   :imported-members:
+   :members:
+   :undoc-members:
+

docs/api/ts_map.rst

@@ -0,0 +1,7 @@
+TS Map
+======
+
+.. automodule:: cosipy.ts_map
+   :imported-members:
+   :members:
+   :undoc-members:

docs/conf.py

@@ -10,11 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-import cosipy
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
 
@@ -23,7 +21,8 @@
 author = 'COSI Team'
 
 # The full version, including alpha/beta/rc tags
-release = cosipy.__version__
+with open('../cosipy/_version.py') as f:
+    release = f.readline()
 
 # -- General configuration ---------------------------------------------------
 
@@ -50,16 +49,46 @@
 # The master toctree document.
 master_doc = 'index'
 
-# intersphinx
+# mock dependencies so we don't have to install them
+autodoc_mock_imports = ["histpy",
+                        'threeML',
+                        'astromodels',
+                        'past',
+                        'numpy',
+                        'h5py',
+                        'astropy',
+                        'healpy',
+                        'mhealpy',
+                        'sparse',
+                        'matplotlib',
+                        'yaml',
+                        'scoords',
+                        'pandas',
+                        'tqdm',
+                        'scipy']
+
+# There seems to be a conflict between unittest.mock (used by sphinx) and metaclasses
+# The cosipy.threeml.custom_functions.Band_Eflux includes a metaclass from
+# astromodels.functions.function, so we mock that one manually with the mock package
+import mock
+
+MOCK_MODULES = ['astromodels.functions.function']
+for mod_name in MOCK_MODULES:
+    sys.modules[mod_name] = mock.Mock()
+
+# intersphinx for mocked dependencies
 
 intersphinx_mapping = {
     'histpy': ('https://histpy.readthedocs.io/en/latest', None),
+    'threeML': ('https://threeml.readthedocs.io/en/latest/', None),
+    'astromodels': ('https://astromodels.readthedocs.io/en/latest/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
     'h5py' : ('https://docs.h5py.org/en/stable/', None),
     'astropy' : ('https://docs.astropy.org/en/stable', None),
     'python' : ('https://docs.python.org/3', None),
     'mhealpy' : ('https://mhealpy.readthedocs.io/en/latest/', None),
     'sparse' : ('https://sparse.pydata.org/en/stable/', None),
-    'gammapy' : ('https://docs.gammapy.org/dev', None),
+    'matplotlib' : ('https://matplotlib.org/stable/', None),
     'scipy' : ('https://scipy.github.io/devdocs', None),
   }
 
@@ -87,29 +116,3 @@
 
 # Extensions to theme docs
 
-# Fix issue with Napoleon RTD that displays "Variables" instead of "Attributes"
-# credit - https://michaelgoerz.net/notes/extending-sphinx-napoleon-docstring-sections.html
-
-from sphinx.ext.napoleon.docstring import GoogleDocstring
-
-# first, we define new methods for any new sections and add them to the class
-def parse_keys_section(self, section):
-    return self._format_fields('Keys', self._consume_fields())
-GoogleDocstring._parse_keys_section = parse_keys_section
-
-def parse_attributes_section(self, section):
-    return self._format_fields('Attributes', self._consume_fields())
-GoogleDocstring._parse_attributes_section = parse_attributes_section
-
-def parse_class_attributes_section(self, section):
-    return self._format_fields('Class Attributes', self._consume_fields())
-GoogleDocstring._parse_class_attributes_section = parse_class_attributes_section
-
-# we now patch the parse method to guarantee that the the above methods are
-# assigned to the _section dict
-def patched_parse(self):
-    self._sections['keys'] = self._parse_keys_section
-    self._sections['class attributes'] = self._parse_class_attributes_section
-    self._unpatched_parse()
-GoogleDocstring._unpatched_parse = GoogleDocstring._parse
-GoogleDocstring._parse = patched_parse

docs/index.rst

@@ -1,11 +1,34 @@
 Welcome to cosipy's documentation!
 ==================================
 
+The cosipy library is `COSI <https://cosi.ssl.berkeley.edu/>`_'s high-level analysis software. It allows you to extract imaging and spectral information from the data, as well as to perform statistical model comparisons. The cosipy products are meant to be ready for interpretation.
+
+The main repository is hosted at https://github.com/cositools/cosipy
+
+In the following sections you will find:
+
+- Installation instructions
+- A tutorial series explaining the basics of various components of cosipy
+- Further usage examples
+- The Application Programming Interface (API), describes the various available classes, their properties, and usage.
+
+.. warning::
+   While many features are already available, cosipy is still actively under development. COSI is scheduled to launch in 2027. In preparation, the cosipy team will be releasing alpha versions with approximately an annual cadence. Your feedback will be greatly appreciated! Note, however, that these are not stable releases and various components can be modified or deprecated shortly.
+
+
+Contributing
+------------
+
+Cosipy is open-source and anyone can contribute. It doesn't matter if you are part of the COSI team or an external contributor. 
+
+The preferred communication channel is the GitHub repository:: if you find a problem, please report it by opening an issue; if you have a question or an idea on how to collaborate, please open a discussion; if you have code to contribute, please fork the repository and open a pull request.
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    install
-   tutorials/Intro.ipynb
    tutorials/index
+   tutorials/other_examples
    api/index