docs: documentation for 3.1.0 release

[cadenmyers13]

closes #73 and #3

Because there is a lot added on this PR (and my commits got a bit messy), here are some instructions for you to clone, install, and build the docs for review:

clone the repo

git clone https://github.com/cadenmyers13/diffpy.cmi.git
cd diffpy.cmi
git checkout cli-docs

create the env and install

conda create -n cmi-review python=3.13
conda activate cmi-review
pip install .

build the docs

cmi install docs
cd docs && make html && open build/html/index.html

cleanup

To remove the clone, run

rm -rf diffpy.cmi

[cadenmyers13]

@sbillinge ready for review

[sbillinge]

Thanks @cadenmyers13 these instructions were super helpful. Just fyi, I got this on the build though:

$ cmi install docs
cd docs && make html && open build/html/index.html
INFO: Installing pack: docs
INFO: conda batch (conda-forge): sphinx sphinx_rtd_theme sphinx-copybutton doctr m2r
INFO: Requirements installation complete.
INFO: Pack 'docs' installation complete.
bash: make: command not found

are we missing make from the docs pack requirements? It is possible that it is only needed on windows?

[sbillinge]

@cadenmyers13 these docs are amazing! Fantastic. One small suggestion might be a pathway for getting started. Everything flowed really well and was super clear and positive up through the cli. But then it switched straight to the API docs which are pretty impenetrable. A smoother flow would be kind of "ok, you have cmi installed, what next?" kind of thing. Then some words about how, actually it is used by writing python scripts in modules or using jupyter and some very simple example, maybe just screen-shots and a link to the example. The best would be the minimal example, e..g., the code to do the line fit? Then I would say, ok, to get started copy the examples and run through them kind of thing.

[cadenmyers13]

are we missing make from the docs pack requirements? It is possible that it is only needed on windows?

Interesting, I didnt hit this problem. Based off this i think it is a windows thing: https://stackoverflow.com/questions/65471557/make-html-not-working-for-sphinx-documentation-in-windows-10.

The responder here recommends using .\make.bat html.

these docs are amazing! Fantastic.

@sbillinge Thank you!

A smoother flow would be kind of "ok, you have cmi installed, what next?" kind of thing. Then some words about how, actually it is used by writing python scripts in modules or using jupyter and some very simple example, maybe just screen-shots and a link to the example. The best would be the minimal example,

I agree, I'll work on this right now.