Docs

LM-SAL · Dec 7, 2023 · 198595e · 198595e
1 parent 487a257
commit 198595e
Show file tree

Hide file tree

Showing 9 changed files with 201 additions and 174 deletions.
diff --git a/.gitignore b/.gitignore
@@ -143,6 +143,7 @@ media
 static
 
 # Specifc Template
+docs/sg_execution_times.rst
 docs/_build
 docs/generated
 docs/api

diff --git a/docs/code_ref/index.rst b/docs/code_ref/index.rst
@@ -1,3 +1,5 @@
+.. _aia_api_reference:
+
 =============
 API reference
 =============

diff --git a/docs/conf.py b/docs/conf.py
@@ -51,7 +51,7 @@
 source_suffix = ".rst"
 master_doc = "index"
 default_role = "obj"
-ogp_image = "https://gitlab.com/LMSAL_HUB/aia_hub/aiapy/-/raw/main/docs/_static/sdo.png"
+ogp_image = "https://github.com/LM-SAL/aiapy/blob/main/docs/_static/sdo.png"
 ogp_use_first_image = True
 ogp_description_length = 160
 ogp_custom_meta_tags = [

diff --git a/docs/develop.rst b/docs/develop.rst
@@ -1,10 +1,10 @@
-.. _dev-guide:
+.. _aiapy_dev-guide:
 
 ============
 Contributing
 ============
 
-Contributing to open source projects is a fantastic way to advance one's coding skills; it's trying to create something, making mistakes, and learning from those mistakes.
+Contributing to open source projects is a good way to advance one's coding skills; it's trying to create something, making mistakes, and learning from those mistakes.
 That's how we all improve, and we are happy to help others learn.
 
 Being an open source contributor doesn't just mean writing code, either.
@@ -14,126 +14,26 @@ Some of these contributions may be the most valuable to the project as a whole,
 Issue Tracking
 --------------
 
-All bugs, feature requests, and other issues related to ``aiapy`` should be recorded using the GitLab issue tracker.
-You can find instructions for how to create an issue `here <https://docs.gitlab.com/ee/user/project/issues/create_new_issue.html>`__.
+All bugs, feature requests, and other issues related to ``aiapy`` should be recorded using the GitHub issue tracker.
+You can find instructions for how to create an issue `here <https://github.com/LM-SAL/aiapy/issues>`__.
 
 All conversation regarding these issues should take place on the issue tracker.
 When a merge request resolves an issue, the issue will be closed and the appropriate merge request will be referenced.
 Issues will not be closed without a reason given.
 
-Creating a fork
----------------
+Code
+----
 
 If you would like to contribute to ``aiapy``, you will first need to setup your development environment.
-First create a fork of the main ``aiapy`` repository under your GitLab username.
-You can find the instructions for how to do this `here <https://docs.gitlab.com/ee/gitlab-basics/fork-project.html>`__.
-If you don't already have an account on GitLab, you'll need to create one.
-You can also sign into GitLab using your GitHub username.
 
-Next, clone your fork of ``aiapy`` to your local machine,
+We suggest reading through the `SunPy developer's guide`_ for a more detailed description of the development process, as we follow there process for ``aiapy``.
 
-.. code:: shell
-
-    git clone https://gitlab.com/<your_username>/``aiapy``.git
-
-Now add the main ``aiapy`` repository as an upstream repository,
-
-.. code:: shell
-
-    git remote add upstream https://gitlab.com/LMSAL_HUB/aia_hub/``aiapy``.git
-
-You can now keep your fork up to date with main repository by running,
-
-.. code:: shell
-
-    git pull upstream main
-
-Installation
--------------
-
-If you're using the `Miniconda Python distribution <https://docs.conda.io/en/latest/miniconda.html>`__ (recommended),
-create a new environment for ``aiapy`` development,
-
-.. code-block:: shell
-
-    conda create --name ``aiapy``-dev pip
-    conda activate ``aiapy``-dev
-
-If you're using an alternate python installation, you can also use `virtual environments <https://docs.python.org/3/tutorial/venv.html>`__.
-Next, install the needed dependencies,
-
-.. code-block:: shell
-
-    cd aiapy
-    pip install -e .[test,docs]
-
-This includes all of the dependencies for the package as well as ``pytest`` for running tests and ``sphinx`` for building the docs.
-
-To make sure everything is working alright, you can run the tests,
-
-.. code-block:: shell
-
-    pytest --remote-data=any
-
-See :ref:`tests` for more details regarding running the tests.
-
-Making a contribution
----------------------
-
-If you want to add a feature or bugfix to ``aiapy``, start by first making sure the main branch of your fork is up to date with the main branch of the main repository (see above, this will help to prevent potential file conflicts).
-Next, create a new branch and switch to it,
-
-.. code:: shell
-
-    git checkout -b my-new-feature
-
-After you've made your changes, commit and push them up to GitLab,
-
-.. code:: shell
-
-    git add changed_file_1.py changed_file_2.py
-    git commit -m "short description of my change"
-    git push origin my-new-feature
-
-Once you see the changes in GitLab, create a merge request against the main ``aiapy`` repository.
-You can find instructions for how to do this `here <https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html>`__.
-Others will likely have comments and suggestions regarding your proposed changes.
-You can make these changes using the instructions listed above.
-
-At least one other ``aiapy`` developer must approve your changes before the code can be merged.
-Additionally, all automated tests should pass and all conversations should be resolved.
-Once these steps are complete, the code can be merged and you can delete  your branch ``my-new-feature``.
-
-.. _tests:
+This will hopefully make it easier for you to contribute to ``aiapy`` and other SunPy affiliated packages in the future.
+If you encounter any problems, please don't hesitate to ask for help on any of our communication channels (found on the landing page of the documentation).
 
 Testing
 -------
 
-Before committing any changes, you should ensure that the all of the tests pass locally.
-To run the tests,
-
-.. code:: shell
-
-    pytest --remote-data=any
-
-This will generate report showing which tests passed and which failed (if any).
-Dropping the ``--remote-data`` flag will skip tests that require a network connection.
-``aiapy`` uses the `pytest <https://pytest.org/en/latest/>`__ framework for discovering and running all of the tests.
-
-Additions to the codebase should be accompanied by appropriate tests such that the test coverage of the entire package does not decrease.
-You can check the test coverage by running,
-
-.. code:: shell
-
-    pytest --remote-data=any --cov aiapy
-
-Additionally, the test suite, including the documentation build and code style checks can be run with `tox <https://tox.readthedocs.io/en/latest/>`__.
-See the `SunPy developer's guide`_ for more information on running the test suite with ``tox``.
-
-Tests should be added to the directory in the appropriate subpackage, e.g. for ``calibrate``, the tests should be placed in ``calibrate/tests``.
-Your tests can be added to an existing file or placed in a new file following the naming convention ``test_*.py``.
-This organization allows the tests to be automatically discovered by pytest.
-
 There are several tests that require a working installation of `sswidl <http://www.lmsal.com/solarsoft/>`__ in order to compare results from IDL and Python.
 This is managed via the `hissw <https://github.com/wtbarnes/hissw/>`__ package.
 If you'd like to run these tests, you must first tell ``hissw`` where to find your IDL and SSW installations by placing the following lines in the file: ``$HOME/.hissw/hisswrc``,
@@ -148,26 +48,11 @@ where ``ssw_home`` is the path to the top of the sswidl tree and ``idl_home`` is
 For more details, see the `hissw documentation <https://wtbarnes.github.io/hissw/>`__.
 If a working installation is not available, these tests are automatically skipped.
 
-Documentation
--------------
-
-All documentation is written in `reStructuredText <https://docutils.sourceforge.io/rst.html>`__ and rendered using `Sphinx <https://www.sphinx-doc.org/en/master/>`__.
-Documentation strings are automatically pulled from all modules, functions and classes to create the API documentation.
-You can build and test the documentation locally by running,
-
-.. code:: shell
-
-    cd docs
-    make html
-
-This will run Sphinx on the restructured text files in order to create the HTML version of the documentation.
-The built documentation, in HTML format, is in ``docs/_build/html``.
-
-Best practices
---------------
+Standards
+---------
 
 All contributors to the ``aiapy`` codebase should follow the `SunPy developer's guide`_.
 This guide lays out a set of best practices for contributing, reviewing, testing, and documenting code.
 All contributions to ``aiapy`` must adhere to the `Python in Heliophysics Community Standards <https://doi.org/10.5281/zenodo.2529130>`__.
 
-.. _`SunPy developer's guide`: https://docs.sunpy.org/en/latest/dev_guide/index.html
+.. _`SunPy developer's guide`: https://docs.sunpy.org/en/latest/dev_guide/contents/newcomers.html
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,36 +1,76 @@
+.. _aia_docs_index:
+
+===================
 aiapy documentation
 ===================
 
-``aiapy`` is a Python package for analyzing data from the Atmospheric Imaging Assembly (AIA) instrument onboard the Solar Dynamics Observatory (SDO) spacecraft.
+``aiapy`` is a Python library for analyzing data from the Atmospheric Imaging Assembly (AIA) instrument onboard the Solar Dynamics Observatory (SDO) spacecraft.
 
-``aiapy`` includes software for converting AIA images from level 1 to level 1.5, point spread function deconvolution, and computing the wavelength and temperature response functions for the EUV channels.
+It allows for converting AIA images from level 1 to level 1.5, point spread function deconvolution, and computing the wavelength and temperature response functions for the EUV channels.
 
 .. grid:: 1 2 2 2
-    :gutter: 3
+    :gutter: 2
+
+    .. grid-item-card:: Hands on guide
+        :link: aiapy-handson-index
+        :link-type: ref
+        :text-align: center
+
+        :material-outlined:`accessibility_new;8em;sd-text-secondary`
+
+        **New users start here!**
+        Walkthrough on how to install aiapy and use the key features of the package.
+
+    .. grid-item-card:: Example gallery
+        :link: generated/gallery
+        :text-align: center
+
+        :material-outlined:`palette;8em;sd-text-secondary`
+
+        Examples including plots on accomplishing common tasks using aiapy.
+
+    .. grid-item-card:: Reference
+        :link: aia_api_reference
+        :link-type: ref
+        :text-align: center
+
+        :material-outlined:`code;8em;sd-text-secondary`
+
+        Technical description of the inputs, outputs, and behavior of each component of aiapy.
+
+    .. grid-item-card:: Get Help
+        :text-align: center
+
+        :material-outlined:`live_help;8em;sd-text-secondary`
 
-    .. grid-item-card::
-        :class-card: card
+        .. button-link:: https://app.element.io/#/room/#sunpy:openastronomy.org
+            :shadow:
+            :expand:
+            :color: warning
 
-        Getting started
-        ^^^^^^^^^^^^^^^
+            **Join the chat**
 
-        .. toctree::
-            :maxdepth: 1
+        .. button-link:: https://github.com/LM-SAL/aiapy/issues
+            :shadow:
+            :expand:
+            :color: warning
 
-            getting_started
-            preparing_data
-            generated/gallery/index
-            code_ref/index
+            **Report an issue**
 
-    .. grid-item-card::
-        :class-card: card
+        .. button-link:: https://community.openastronomy.org/c/sunpy/5
+            :shadow:
+            :expand:
+            :color: warning
 
-        Other info
-        ^^^^^^^^^^
+            **Post on Discourse**
 
-        .. toctree::
-            :maxdepth: 1
+.. toctree::
+    :maxdepth: 1
+    :hidden:
 
-            citation
-            changelog
-            develop
+    tutorial/index
+    generated/gallery/index
+    code_ref/index
+    citation
+    changelog
+    develop
diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst
@@ -0,0 +1,16 @@
+.. _aiapy-handson-index:
+
+********************
+aiapy hands on guide
+********************
+
+Welcome to the introductory guide for the ``aiapy`` library.
+``aiapy`` is a community-developed, free and open-source library to to convert AIA images from level 1 to level 1.5, compute point spread function deconvolution, and computing the wavelength and temperature response functions for the EUV channels.
+
+This guide assumes you know how to run code in Python and are famailer with the other packages within in the scientific Python ecosystem, including SunPy, Astropy, NumPy, and Matplotlib.
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   preparing_data