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]

The API page is empty

I think it is because the error

WARNING: autodoc: failed to import module 'pyobjcryst'; the following exception was raised:
No module named 'pyobjcryst._pyobjcryst' [autodoc.import_object]

I installed pyobjcrst by

pip install -e.

Are there any additional steps to install pyobjcrst?

[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

[ycexiao]

@Tieqiong, thank you. After running

conda install scons
scons -j4 dev
cd docs
make html

I get

WARNING: autodoc: failed to import module 'pyobjcryst'; the following exception was raised:
pyobjcryst/src/pyobjcryst/_pyobjcryst.so: undefined symbol: _ZN5boost6python7objects7add_docERKNS0_3api6objectEPKc [autodoc.import_object]

I also tried to install pyobjcrst in development mode as described in README. Following the steps, I ran scons -j4 test, and I got

src/pyobjcryst/atom.py:27: in <module>
    from pyobjcryst._pyobjcryst import Atom
E   ImportError: pyobjcryst/src/pyobjcryst/_pyobjcryst.so: undefined symbol: _ZN5boost6python7objects7add_docERKNS0_3api6objectEPKc

Could you please help me with the installation problem?

[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.