doc: fix documentation rendering

[cadenmyers13]

docs fail to build locally after moving from doc/manual/source to doc/source

[sbillinge]

We should talk to Andrew about this. Ideally we want to move away from the old manual workflow.

[sbillinge]

....but thanks for pointing this out, I had overlooked it.

[sbillinge]

@cadenmyers13 do you have any cmi scripts you can quickly run to test the code in the migration branch?

[cadenmyers13]

do you have any cmi scripts you can quickly run to test the code in the migration branch?

@sbillinge Let me look

Also, i realized this was done in the migration branch (sweet!) so we can close this issue

[sbillinge]

workflow:

1. run your scripts in your current cmi env
2. create a new env for cmi
3. conda remove --force diffpy.srfit
4. pip install -e <path/to/diffpy.srfit with migration branch fetched and checked out>
5. rerun the scripts
6. check that the results are identical

[sbillinge]

@cadenmyers13 when this is done let me know and I will merge to main. Let's do the docs on a separate PR. Please could you do me a favor and make an issue to do that?

[cadenmyers13]

@sbillinge Okay I tested some (rather horrible lol) fits for Jon Owen's group and got the same results for the same data so it looks like its working!

diffpy.srfit on python 3.7

diffpy.srfit on python 3.12

[sbillinge]

urgh, the fits are hoorible, but also the colors. Please don't tell me you are not using the group matplotlib style files......?

but thanks for testing!

[cadenmyers13]

@sbillinge no these are the python default colors

[ycexiao]

@sbillinge
Running make html in the upstream/migration raises

    AttributeError: module 'docutils.nodes' has no attribute 'reprunicode'

It can be fixed by replacing m2r in docs/source/conf.py with m2r2. After removing the two diffpy.srfit.example_package.rst and diffpy.srfit.rst example files, there are still a lot of errors. Mainly due to that sphinx can't parse the old docstring style in the src.

e.g. diffpy.srfit.equation.builder.EquationFactory.makeEquation

Arguments
eqstr       --  An equation in string form using standard python
                syntax.  The equation string can use any function
                registered literal or function, including numpy ufuncs
                that are automatically registered.

It will get ERROR: Unexpected indentation.

These kinds of errors are everywhere because the docstring is not written a way sphinx can parse. Do we want to rewrite all the docstrings, or come up with some temporary solutions?

Temporary solutions like

Arguments
---------
eqstr       --  An equation in string form using standard python
                syntax.  The equation string can use any function
                registered literal or function, including numpy ufuncs
                that are automatically registered.

can mute the errors. But the api still can not be rendered because sphinx can't parse them correctly.

We can also remove the section for the package API in this release and rewrite the docstring later.

[sbillinge]

yah, we didn't work on the docs for this.

Here is my suggestion. If the docstrings are sufficiently "normalized" in a format, could we write a quick converter function that will put them to the desired format?

Please could you also check other packages that were written around the same time, like diffpy.structure and so on. What do the docstrings look like there?

Initially, we can release without API docs built, but it would sure be nice to have the API docs rendering properly in the long run. Could you look into it and we can decide. If we do this, chatgpt can help, but we should test on just a few docsstrings and really check it carefully before running on everything.