docs: fix documentation rendering with scikit-package standards.

[ycexiao]

What problem does this PR address?

Fix the documentation rendering.

What should the reviewer(s) do?

Please check the rendered documentation.

[ycexiao]

@sbillinge, it's ready for review.

[ycexiao]

Examples with .ipynb files are moved from the top-level directory into the docs directory, as other diffpy packages do.

[sbillinge]

I think these should be in the top level tbh. These are examples for users, not source for docs so it doesn't make so much sense to me to put them into docs/source. It kind of depends whether the examples are just going to appear in the rst or whether we expect users to be able to import and run them. They won't get bundled in the release, but at least they are more accessible (in docs/examples in the repo)

[sbillinge]

wait, scratch my comment. As long as it is docs/examples I am happy...

[sbillinge]

Well, actualy, thinking again, this change we may want to run by @vincefn to see his preference. I could also see examples at the top level making them more discoverable. I think if it were my choice I would do docs/examples but let's give @vincefn a chance to puah back before we merge this.

[ycexiao]

examples/index.rst is renamed to examples/examples.rst.

[ycexiao]

@sbillinge , is it ready for merging?

[vincefn]

Who should I add as maintainer on readthedocs, so you can also test the version generated there ?

[Tieqiong]

Are there any additional steps to install pyobjcrst?

@ycexiao
please run
conda install scons
and
scons -j4 dev

This will produce a _pyobjcryst.* in your src/pyobjcryst. Then generate api and build html again. You should be able to see the modules and C++ signatures

[sbillinge]

Who should I add as maintainer on readthedocs, so you can also test the version generated there ?

@vincefn please could you add me (@sbillinge )

[sbillinge]

@vincefn quick question. Do you mind if we move Examples under docs (current standard in diffpy) or do you want to keep them at the top level (e.g., for easier discovery)? Ok to do it either way so just let us know.

[Tieqiong]

Could you please help me with the installation problem?

@ycexiao what's the status now? Maybe you can post your screenshot here for reference. Thanks

[ycexiao]

Could you please help me with the installation problem?

@ycexiao what's the status now? Maybe you can post your screenshot here for reference. Thanks

Thank you, the message is outdated. We have solved this through Slack.

[sbillinge]

@ycexiao please could you summarize where we are with everything on this PR? I think, but not sure, that we have discussed:

1. moving examples to docs/examples. Status: waiting to hear vincefn preferrence
2. discussed building richer API docs with docstrings from the c-code. Status: not sure the status
3. discussed whether to deploy docs to gh-pages or to readthedocs. Status: Status: waiting to hear vincefn preferrence
4. not discussed but pertinent: whether to change the theme to pydata as per pyobjcryst current docs.

[ycexiao]

discussed building richer API docs with docstrings from the c-code. Status: not sure the status

@sbillinge
We can parse the C code via doxygen and create the C API using breathe, an extension for sphinx. It has a good rendering effect for well-documented classes and functions.

To add C API:

1. Install doxygen and breathe.
2. Edit Doxyfile, which is like conf.py to sphinx
3. Run doxygen Doxyfile.
4. Add breathe dependence and settings in conf.py
5. Add links to the C files/class/functions in rst files.
6. Run make html. And the C API page is included in the documentation.

We can modify Makefile so that we don't need to run doxygen manually. Please see if it is a good way to add C API pages. If it is, I will refine my current setups and commit them to this PR.

[Tieqiong]

@ycexiao we don't need these to render the c api. The current method is fine, just remember to generate your extension module locally and sphinx will do everything for you.
But if we want all the hyperlinks for c types, maybe this is the way to go?