From 28aa9db5af9d3e70494afde39e86e11ea3206a6f Mon Sep 17 00:00:00 2001 From: Nabil Freij Date: Thu, 2 Nov 2023 11:23:58 -0700 Subject: [PATCH] Docs --- docs/code_ref/index.rst | 2 + docs/conf.py | 2 +- docs/develop.rst | 139 +++---------------------- docs/getting_started.rst | 24 ----- docs/index.rst | 84 +++++++++++---- docs/tutorial/index.rst | 16 +++ docs/tutorial/installation.rst | 104 ++++++++++++++++++ docs/{ => tutorial}/preparing_data.rst | 3 + 8 files changed, 200 insertions(+), 174 deletions(-) delete mode 100644 docs/getting_started.rst create mode 100644 docs/tutorial/index.rst create mode 100644 docs/tutorial/installation.rst rename docs/{ => tutorial}/preparing_data.rst (97%) diff --git a/docs/code_ref/index.rst b/docs/code_ref/index.rst index e41a898..f1fb0af 100644 --- 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 index a0484cc..a224127 100644 --- 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 index 32e8fac..02feb4e 100644 --- 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 `__. +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 `__. 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 `__. -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//``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 `__ (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 `__. -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 `__. -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 `__ 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 `__. -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 `__ in order to compare results from IDL and Python. This is managed via the `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 `__. If a working installation is not available, these tests are automatically skipped. -Documentation -------------- - -All documentation is written in `reStructuredText `__ and rendered using `Sphinx `__. -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 `__. -.. _`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 deleted file mode 100644 index 12dcec1..0000000 --- a/docs/getting_started.rst +++ /dev/null @@ -1,24 +0,0 @@ -Getting Started -=============== - -The stable version of ``aiapy`` is available through both PyPI via ``pip``, - -.. code-block:: shell - - pip install aiapy - -as well as through the `Miniconda distribution `__ via ``conda-forge``, - -.. code-block:: shell - - conda install -c conda-forge aiapy - -You can also install the development version from GitLab, - -.. code-block:: shell - - git clone https://gitlab.com/LMSAL_HUB/aia_hub/aiapy.git - cd aiapy - pip install -e ".[dev]" - -If you will be developing ``aiapy``, please see the :ref:`dev-guide`. diff --git a/docs/index.rst b/docs/index.rst index 86e33a7..23b85e8 100644 --- 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 new file mode 100644 index 0000000..e2374f4 --- /dev/null +++ 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 diff --git a/docs/tutorial/installation.rst b/docs/tutorial/installation.rst new file mode 100644 index 0000000..11581b1 --- /dev/null +++ b/docs/tutorial/installation.rst @@ -0,0 +1,104 @@ +.. _aiapy-handson-installing: + +************ +Installation +************ + +This is the first chapter in the aiapy hands on, and by the end of it you should have a working installation of Python and ``aiapy``. + +Installing Python +================= + +There are many ways to install Python, but even if you have Python installed somewhere on your computer we recommend following these instructions anyway. +That's because we will create a new Python environment. +As well as containing a Python installation, this environment provides an isolated place to install Python packages (like ``aiapy``) without affecting any other current Python installation. +If you already have Python and either ``conda`` or ``pip`` working you can skip the next section. + +Installing miniforge +-------------------- + +If you don't already have a Python installation then we recommend installing Python with `miniforge `__. +This will install ``conda`` and automatically configure the default channel (a channel is a remote software repository) to be ``conda-forge``, which is where ``aiapy`` is available. + +First, download the installer for your system and architecture from the links below: + +.. grid:: 3 + + .. grid-item-card:: Linux + + `x86-64 `__ + + `aarch64 `__ + + `ppc64le `__ + + .. grid-item-card:: Windows + :link: https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe + + `x86-64 `__ + + .. grid-item-card:: Mac + + `x86-64 `__ + + `arm64 (Apple + Silicon) `__ + +Then select your platform to install miniforge: + +.. tab-set:: + + .. tab-item:: Linux & Mac + :sync: platform + + Linux & Mac Run the script downloaded above, with + ``bash ``. The following should work: + + .. code-block:: console + + bash Miniforge3-$(uname)-$(uname -m).sh + + Once the installer has completed, close and reopen your terminal. + + .. tab-item:: Windows + :sync: platform + + Double click the executable file downloaded from + the links above. + + Once the installer has completed you should have a new "miniforge + Prompt" entry in your start menu. + +In a new terminal (miniforge Prompt on Windows) run ``conda list`` to test that the install has worked. + +Installing aiapy +---------------- + +To install ``aiapy``, start by launching a terminal (under a UNIX-like system) or the miniforge Prompt (under Windows). +Now we will create and activate new virtual environment to install ``aiapy`` into: + +.. code-block:: bash + + $ conda create --name aiapy + # Only run the following two lines + # if you have NOT installed miniforge or added conda-forge to your channels + $ conda config --add channels conda-forge + $ conda config --set channel_priority strict + $ conda activate aiapy + +In this case the environment is named 'aiapy'. +Feel free to change this to a different environment name. + +The benefit of using a virtual environment is that it allows you to install packages without affecting any other Python installation on your system. +This also means you can work on multiple projects (research or coding) with different package requirements without them interfering with each other. + +Now we have a fresh environment we can install ``aiapy``: + +.. code-block:: bash + + $ conda install aiapy + +This will install ``aiapy`` and all of its dependencies. +If you want to install another package later, you can run ``conda install ``. + +Now we've got a working installation of ``aiapy``, in the next few chapters we'll look at some of the basic data structures ``aiapy`` uses for representing times, coordinates, and data with physical units. diff --git a/docs/preparing_data.rst b/docs/tutorial/preparing_data.rst similarity index 97% rename from docs/preparing_data.rst rename to docs/tutorial/preparing_data.rst index 8b06648..30f99f8 100644 --- a/docs/preparing_data.rst +++ b/docs/tutorial/preparing_data.rst @@ -1,3 +1,6 @@ +.. _aiapy_prepping_level_1_data: + +================== Preparing AIA data ==================