docs: documentation for 3.1.0 release

.github/ISSUE_TEMPLATE/new_pack_proposal.md

@@ -0,0 +1,37 @@
+---
+name: New Pack Proposal
+about: Interested in contributing a new pack? Follow the instructions here!
+title: "feat: add `<your-pack-name>` to `diffpy.cmi`"
+labels: ""
+assignees: ""
+---
+
+## Pack description
+
+<pack description here>
+
+## Pack submission checklist
+
+- [ ] Fork and clone this repository and cd to the top level by running `cd diffpy.cmi`.
+- [ ] Create a requirements file by running `touch requirements/packs/<your-pack-name>.txt`. List all dependencies for your pack.
+- [ ] (OPTIONAL) Create a directory to place your examples, if applicable, by running `mkdir docs/examples/<your-pack-name>/<your-example-name>`.
+- [ ] (OPTIONAL) Copy your example scripts and data under the directory you just made. If you have multiple examples, house them under their own separate directory (i.e. `.../<your-pack-name>/example1` and `.../<your-pack-name>/example2`).
+- [ ] List your pack and its dependencies under `docs/source/available-packs.rst` using the same format as the other packs. In this same file, add a description of your pack (1-2 sentences is recommended).
+- [ ] Give yourself credit by listing your name and contributors to the pack you've created!
+
+## Local testing
+
+- [ ] Test to make sure the addition of your new pack worked by first creating a new environment and installing from source. Do this by running the following commands:
+
+```
+conda create -n testcmi-env diffpy.cmi
+conda activate testcmi-env
+pip install -e .
+cmi install docs tests
+```
+
+- [ ] Run `cmi info` to see if your pack and any examples you may have added are listed there.
+- [ ] Build and open the docs with the command `cd docs && make html && open build/html/index.html`. Navigate around the docs to make sure everything looks okay.
+- [ ] Lastly, install your pack with `cmi install <your-pack-name>`.
+
+When the above items are complete, make a pull request (PR) with the changes, referencing this issue in the PR (i.e. "closes #issue-number").

.github/ISSUE_TEMPLATE/new_profile_proposal.md

@@ -0,0 +1,31 @@
+---
+name: New Profile Proposal
+about: Interested in contributing a new profile? Follow the instructions here!
+title: "feat: add `<your-profile-name>` to `diffpy.cmi`"
+labels: ""
+assignees: ""
+---
+
+## Profile submission checklist
+
+- [ ] Fork and clone this repository and cd to the top level by running `cd diffpy.cmi`.
+- [ ] Create a requirements file by running `touch requirements/profiles/<your-profile-name>.yml`. List all packs used in this profile under the header `packs:` in a bulleted list. All additional packages used (if any) should be listed under `extras:` in a similar fashion (see [this file](https://github.com/diffpy/diffpy.cmi/blob/main/requirements/profiles/all.yml) for reference). If no additional packages are required, add the `extras:` header but leave the entries empty.
+- [ ] List your profile and its dependencies under `docs/source/available-profiles.rst` using the same format as the other profiles. In this same file, add a description of your profile (1-2 sentences is recommended).
+- [ ] Give yourself credit by listing your name and contributors to the profile you've created!
+
+## Local testing
+
+- [ ] Test to make sure the addition of your new profile worked by first creating a new environment and installing from source. Do this by running the following commands:
+
+```
+conda create -n testcmi-env diffpy.cmi
+conda activate testcmi-env
+pip install -e .
+cmi install docs tests
+```
+
+- [ ] Run `cmi info` to see if your profile is listed there.
+- [ ] Build and open the docs with the command `cd docs && make html && open build/html/index.html`. Navigate around the docs to make sure everything looks okay.
+- [ ] Lastly, install your profile with `cmi install <your-profile-name>`.
+
+When the above items are complete, make a pull request (PR) with the changes, referencing this issue in the PR (i.e. "closes #issue-number").

docs/source/api/diffpy.cmi.rst

@@ -1,18 +1,60 @@
 :tocdepth: -1
 
-|title|
-=======
+diffpy.cmi package
+==================
 
-.. |title| replace:: diffpy.cmi Contents
+.. automodule:: diffpy.cmi
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
-``diffpy.cmi`` includes Python and C++ libraries developed by the DiffPy team as well as external libraries necessary for functionality.
+Submodules
+----------
 
-Libraries developed by the DiffPy team
---------------------------------------
+diffpy.cmi.log module
+^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: ../snippets/diffpy_libraries.rst
+.. automodule:: diffpy.cmi.log
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
-External Libraries
-------------------
+diffpy.cmi.conda module
+^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: ../snippets/external_libraries.rst
+.. automodule:: diffpy.cmi.conda
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.cmi.packsmanager module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.cmi.packsmanager
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.cmi.installer module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.cmi.installer
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.cmi.cli module
+^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.cmi.cli
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.cmi.profilesmanager module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.cmi.profilesmanager
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/available-packs.rst

@@ -0,0 +1,71 @@
+Packs
+-----
+
+This page lists the dependencies required by each ``diffpy.cmi`` pack.
+
+
+====
+core
+====
+
+The ``core`` pack provides the essential building blocks for creating and running regression workflows in ``diffpy.cmi``.
+
+This pack was created by members of the Billinge Group and the DiffPy community.
+
+- ``packaging``
+- ``PyYAML``
+- ``diffpy.utils``
+- ``diffpy.srfit``
+- ``diffpy.structure``
+
+===
+pdf
+===
+
+The ``pdf`` pack is designed to handle pair distribution function (PDF) modeling and analysis.
+
+This pack was created by members of the Billinge Group and the DiffPy community.
+
+- ``diffpy.srreal``
+- ``pyobjcryst``
+
+====
+docs
+====
+
+The ``docs`` pack contains the dependencies required to build the documentation for ``diffpy.cmi``.
+
+- ``sphinx``
+- ``sphinx_rtd_theme``
+- ``sphinx-copybutton``
+- ``doctr``
+- ``m2r``
+
+========
+plotting
+========
+
+The ``plotting`` pack provides tools for plotting and visualizing data.
+
+- ``ipywidgets``
+- ``matplotlib``
+- ``ipympl``
+- ``bg-mpl-stylesheets``
+- ``py3dmol>=2.0.1``
+
+
+=====
+tests
+=====
+
+The ``tests`` pack contains the dependencies required for testing ``diffpy.cmi``.
+
+- ``flake8``
+- ``pytest``
+- ``codecov``
+- ``coverage``
+- ``pytest-cov``
+- ``pytest-env``
+- ``pytest-mock``
+- ``freezegun``
+- ``DeepDiff``

docs/source/available-profiles.rst

@@ -0,0 +1,26 @@
+Profiles
+--------
+
+This page lists the packs and extra dependencies required by each ``diffpy.cmi`` profile.
+
+========
+pdf-plus
+========
+
+A comprehensive pair distribution function profile that includes plotting and Jupyter Notebook support.
+
+This pack was created by members of the Billinge Group and the DiffPy community.
+
+packs: ``core``, ``pdf``, ``plotting``
+
+extras: ``ipykernel``
+
+======
+_tests
+======
+
+Testing and development tools for ``diffpy.cmi``.
+
+packs: ``core``, ``pdf``, ``tests``
+
+extras: ``_pytest.sh tar_url.txt``, ``_pytest.bat tar_url.txt``

docs/source/cli-commands.rst

@@ -0,0 +1,124 @@
+:tocdepth: -1
+
+.. index:: cli-commands
+
+.. _cli-commands:
+
+CMI Command-Line Interface (CLI)
+--------------------------------
+
+The ``cmi`` command provides access to ``diffpy.cmi``.
+It allows users to explore, install, and run **packs**, **profiles**, and **example workflows**.
+
+============
+Getting Help
+============
+
+The ``-h`` flag is available for **all** cmi commands and subcommands.
+It's highly recommended to use it wherever necessary.
+
+To display help for the main CLI, type
+
+.. code-block:: bash
+
+    cmi -h
+    cmi --help
+
+Display help for a specific subcommand with,
+
+.. code-block:: bash
+
+    cmi <subcommand> -h
+
+Open the full online manual in a web browser by typing,
+
+.. code-block:: bash
+
+    cmi --manual
+
+====================
+``cmi info`` command
+====================
+
+To print information about available and installed packs, profiles, and examples, type,
+
+.. code-block:: bash
+
+   cmi info
+
+To print information about packs, profiles, or examples, type
+
+.. code-block:: bash
+
+   cmi info packs
+   cmi info profiles
+   cmi info examples
+
+=======================
+``cmi install`` command
+=======================
+
+To install packs or profiles into your environment, type
+
+.. code-block:: bash
+
+    cmi install <pack-name>
+    cmi install <profile-name>
+
+Installation of multiple packs or profiles is also supported, e.g.,
+
+.. code-block:: bash
+
+    cmi install <pack-name> <profile-name>
+
+====================
+``cmi copy`` command
+====================
+
+To view all examples available to copy, type
+
+.. code-block:: bash
+
+    cmi info examples
+
+To copy an example or list of examples to cwd, type
+
+.. code-block:: bash
+
+    cmi copy <example-name>
+    cmi copy <example-name1> <example-name2>
+
+To copy all examples from a pack or list of packs to cwd, type
+
+.. code-block:: bash
+
+    cmi copy <pack-name>
+    cmi copy <pack-name1> <pack-name2>
+
+To copy all examples to cwd, type
+
+.. code-block:: bash
+
+    cmi copy all
+
+To copy an example to a target directory, type
+
+.. code-block:: bash
+
+    cmi copy <example-name> -t <target-directory>
+
+To force overwrite a preexisting example directory, type
+
+.. code-block:: bash
+
+    cmi copy <example-name> -f
+
+====================
+``cmi env`` command
+====================
+
+To show basic information about your current conda environment, type
+
+.. code-block:: bash
+
+   cmi env

docs/source/conf.py

@@ -148,6 +148,7 @@
 #
 html_theme_options = {
     "navigation_with_keys": "true",
+    "logo_only": True,
 }
 
 # Add any paths that contain custom themes here, relative to this directory.