Skip to content

Commit 02e5279

Browse files
sbillingesbillinge
authored
Merge pull request #78 from cadenmyers13/cli-docs
docs: documentation for 3.1.0 release
2 parents 224741d + 23d8692 commit 02e5279

File tree

23 files changed

+842
-6660
lines changed

23 files changed

+842
-6660
lines changed

‎.github/ISSUE_TEMPLATE/new_pack_proposal.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: New Pack Proposal
3+
about: Interested in contributing a new pack? Follow the instructions here!
4+
title: "feat: add `<your-pack-name>` to `diffpy.cmi`"
5+
labels: ""
6+
assignees: ""
7+
---
8+
9+
## Pack description
10+
11+
<pack description here>
12+
13+
## Pack submission checklist
14+
15+
- [ ] Fork and clone this repository and cd to the top level by running `cd diffpy.cmi`.
16+
- [ ] Create a requirements file by running `touch requirements/packs/<your-pack-name>.txt`. List all dependencies for your pack.
17+
- [ ] (OPTIONAL) Create a directory to place your examples, if applicable, by running `mkdir docs/examples/<your-pack-name>/<your-example-name>`.
18+
- [ ] (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`).
19+
- [ ] 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).
20+
- [ ] Give yourself credit by listing your name and contributors to the pack you've created!
21+
22+
## Local testing
23+
24+
- [ ] 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:
25+
26+
```
27+
conda create -n testcmi-env diffpy.cmi
28+
conda activate testcmi-env
29+
pip install -e .
30+
cmi install docs tests
31+
```
32+
33+
- [ ] Run `cmi info` to see if your pack and any examples you may have added are listed there.
34+
- [ ] 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.
35+
- [ ] Lastly, install your pack with `cmi install <your-pack-name>`.
36+
37+
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‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: New Profile Proposal
3+
about: Interested in contributing a new profile? Follow the instructions here!
4+
title: "feat: add `<your-profile-name>` to `diffpy.cmi`"
5+
labels: ""
6+
assignees: ""
7+
---
8+
9+
## Profile submission checklist
10+
11+
- [ ] Fork and clone this repository and cd to the top level by running `cd diffpy.cmi`.
12+
- [ ] 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.
13+
- [ ] 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).
14+
- [ ] Give yourself credit by listing your name and contributors to the profile you've created!
15+
16+
## Local testing
17+
18+
- [ ] 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:
19+
20+
```
21+
conda create -n testcmi-env diffpy.cmi
22+
conda activate testcmi-env
23+
pip install -e .
24+
cmi install docs tests
25+
```
26+
27+
- [ ] Run `cmi info` to see if your profile is listed there.
28+
- [ ] 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.
29+
- [ ] Lastly, install your profile with `cmi install <your-profile-name>`.
30+
31+
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‎

Lines changed: 52 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,60 @@
11
:tocdepth: -1
22

3-
|title|
4-
=======
3+
diffpy.cmi package
4+
==================
55

6-
.. |title| replace:: diffpy.cmi Contents
6+
.. automodule:: diffpy.cmi
7+
:members:
8+
:undoc-members:
9+
:show-inheritance:
710

8-
``diffpy.cmi`` includes Python and C++ libraries developed by the DiffPy team as well as external libraries necessary for functionality.
11+
Submodules
12+
----------
913

10-
Libraries developed by the DiffPy team
11-
--------------------------------------
14+
diffpy.cmi.log module
15+
^^^^^^^^^^^^^^^^^^^^^
1216

13-
.. include:: ../snippets/diffpy_libraries.rst
17+
.. automodule:: diffpy.cmi.log
18+
:members:
19+
:undoc-members:
20+
:show-inheritance:
1421

15-
External Libraries
16-
------------------
22+
diffpy.cmi.conda module
23+
^^^^^^^^^^^^^^^^^^^^^^^
1724

18-
.. include:: ../snippets/external_libraries.rst
25+
.. automodule:: diffpy.cmi.conda
26+
:members:
27+
:undoc-members:
28+
:show-inheritance:
29+
30+
diffpy.cmi.packsmanager module
31+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
32+
33+
.. automodule:: diffpy.cmi.packsmanager
34+
:members:
35+
:undoc-members:
36+
:show-inheritance:
37+
38+
diffpy.cmi.installer module
39+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
40+
41+
.. automodule:: diffpy.cmi.installer
42+
:members:
43+
:undoc-members:
44+
:show-inheritance:
45+
46+
diffpy.cmi.cli module
47+
^^^^^^^^^^^^^^^^^^^^^
48+
49+
.. automodule:: diffpy.cmi.cli
50+
:members:
51+
:undoc-members:
52+
:show-inheritance:
53+
54+
diffpy.cmi.profilesmanager module
55+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
56+
57+
.. automodule:: diffpy.cmi.profilesmanager
58+
:members:
59+
:undoc-members:
60+
:show-inheritance:

‎docs/source/available-packs.rst‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
Packs
2+
-----
3+
4+
This page lists the dependencies required by each ``diffpy.cmi`` pack.
5+
6+
7+
====
8+
core
9+
====
10+
11+
The ``core`` pack provides the essential building blocks for creating and running regression workflows in ``diffpy.cmi``.
12+
13+
This pack was created by members of the Billinge Group and the DiffPy community.
14+
15+
- ``packaging``
16+
- ``PyYAML``
17+
- ``diffpy.utils``
18+
- ``diffpy.srfit``
19+
- ``diffpy.structure``
20+
21+
===
22+
pdf
23+
===
24+
25+
The ``pdf`` pack is designed to handle pair distribution function (PDF) modeling and analysis.
26+
27+
This pack was created by members of the Billinge Group and the DiffPy community.
28+
29+
- ``diffpy.srreal``
30+
- ``pyobjcryst``
31+
32+
====
33+
docs
34+
====
35+
36+
The ``docs`` pack contains the dependencies required to build the documentation for ``diffpy.cmi``.
37+
38+
- ``sphinx``
39+
- ``sphinx_rtd_theme``
40+
- ``sphinx-copybutton``
41+
- ``doctr``
42+
- ``m2r``
43+
44+
========
45+
plotting
46+
========
47+
48+
The ``plotting`` pack provides tools for plotting and visualizing data.
49+
50+
- ``ipywidgets``
51+
- ``matplotlib``
52+
- ``ipympl``
53+
- ``bg-mpl-stylesheets``
54+
- ``py3dmol>=2.0.1``
55+
56+
57+
=====
58+
tests
59+
=====
60+
61+
The ``tests`` pack contains the dependencies required for testing ``diffpy.cmi``.
62+
63+
- ``flake8``
64+
- ``pytest``
65+
- ``codecov``
66+
- ``coverage``
67+
- ``pytest-cov``
68+
- ``pytest-env``
69+
- ``pytest-mock``
70+
- ``freezegun``
71+
- ``DeepDiff``

‎docs/source/available-profiles.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
Profiles
2+
--------
3+
4+
This page lists the packs and extra dependencies required by each ``diffpy.cmi`` profile.
5+
6+
========
7+
pdf-plus
8+
========
9+
10+
A comprehensive pair distribution function profile that includes plotting and Jupyter Notebook support.
11+
12+
This pack was created by members of the Billinge Group and the DiffPy community.
13+
14+
packs: ``core``, ``pdf``, ``plotting``
15+
16+
extras: ``ipykernel``
17+
18+
======
19+
_tests
20+
======
21+
22+
Testing and development tools for ``diffpy.cmi``.
23+
24+
packs: ``core``, ``pdf``, ``tests``
25+
26+
extras: ``_pytest.sh tar_url.txt``, ``_pytest.bat tar_url.txt``

‎docs/source/cli-commands.rst‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
:tocdepth: -1
2+
3+
.. index:: cli-commands
4+
5+
.. _cli-commands:
6+
7+
CMI Command-Line Interface (CLI)
8+
--------------------------------
9+
10+
The ``cmi`` command provides access to ``diffpy.cmi``.
11+
It allows users to explore, install, and run **packs**, **profiles**, and **example workflows**.
12+
13+
============
14+
Getting Help
15+
============
16+
17+
The ``-h`` flag is available for **all** cmi commands and subcommands.
18+
It's highly recommended to use it wherever necessary.
19+
20+
To display help for the main CLI, type
21+
22+
.. code-block:: bash
23+
24+
cmi -h
25+
cmi --help
26+
27+
Display help for a specific subcommand with,
28+
29+
.. code-block:: bash
30+
31+
cmi <subcommand> -h
32+
33+
Open the full online manual in a web browser by typing,
34+
35+
.. code-block:: bash
36+
37+
cmi --manual
38+
39+
====================
40+
``cmi info`` command
41+
====================
42+
43+
To print information about available and installed packs, profiles, and examples, type,
44+
45+
.. code-block:: bash
46+
47+
cmi info
48+
49+
To print information about packs, profiles, or examples, type
50+
51+
.. code-block:: bash
52+
53+
cmi info packs
54+
cmi info profiles
55+
cmi info examples
56+
57+
=======================
58+
``cmi install`` command
59+
=======================
60+
61+
To install packs or profiles into your environment, type
62+
63+
.. code-block:: bash
64+
65+
cmi install <pack-name>
66+
cmi install <profile-name>
67+
68+
Installation of multiple packs or profiles is also supported, e.g.,
69+
70+
.. code-block:: bash
71+
72+
cmi install <pack-name> <profile-name>
73+
74+
====================
75+
``cmi copy`` command
76+
====================
77+
78+
To view all examples available to copy, type
79+
80+
.. code-block:: bash
81+
82+
cmi info examples
83+
84+
To copy an example or list of examples to cwd, type
85+
86+
.. code-block:: bash
87+
88+
cmi copy <example-name>
89+
cmi copy <example-name1> <example-name2>
90+
91+
To copy all examples from a pack or list of packs to cwd, type
92+
93+
.. code-block:: bash
94+
95+
cmi copy <pack-name>
96+
cmi copy <pack-name1> <pack-name2>
97+
98+
To copy all examples to cwd, type
99+
100+
.. code-block:: bash
101+
102+
cmi copy all
103+
104+
To copy an example to a target directory, type
105+
106+
.. code-block:: bash
107+
108+
cmi copy <example-name> -t <target-directory>
109+
110+
To force overwrite a preexisting example directory, type
111+
112+
.. code-block:: bash
113+
114+
cmi copy <example-name> -f
115+
116+
====================
117+
``cmi env`` command
118+
====================
119+
120+
To show basic information about your current conda environment, type
121+
122+
.. code-block:: bash
123+
124+
cmi env

‎docs/source/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,7 @@
148148
#
149149
html_theme_options = {
150150
"navigation_with_keys": "true",
151+
"logo_only": True,
151152
}
152153

153154
# Add any paths that contain custom themes here, relative to this directory.

0 commit comments

Comments
 (0)