Readthedocs

[AurelienJaquier]

Description

@anilbey it looks like we cannot use cd in readthedocs, so I had to copy back the rst converting code to .readthedocs.yml with updated paths.

Checklist:

• Unit tests are added to cover the changes (skip if not applicable).
• The changes are mentioned in the documentation (skip if not applicable).
• CHANGELOG file is updated (skip if not applicable).

[anilbey]

I see. Would it not work if we keep the script paths relative to the repository directory and call it from both .tox and .readthedocs?
E.g. instead of this tox block

changedir = docs

commands =
    sh examples_to_rst.sh
    # build the docs to see if it builds fine
    make html SPHINXOPTS=-W
    # make sure the feature names and units are up-to-date
    pytest test_feature_units_in_docs.py

This following will run the script without changing the path.

commands =
    sh examples_to_rst.sh  # assuming we are inside the root EFEL folder, not EFEL/docs folder
    cd docs
    # build the docs to see if it builds fine
    make html SPHINXOPTS=-W
    # make sure the feature names and units are up-to-date
    pytest test_feature_units_in_docs.py

What do you think?

[AurelienJaquier]

doing cd inside tox does not work either, I stay at the root :/

[anilbey]

I think we can find a solution.

[anilbey]

tox.ini

commands =
    sh docs/examples_to_rst.sh
    # build the docs to see if it builds fine
    sphinx-build -b html -W docs/source docs/_build/html
    # make sure the feature names and units are up-to-date
    pytest docs/test_feature_units_in_docs.py

examples_to_rst.sh

jupyter nbconvert --to rst examples/sonata-network/sonata-network.ipynb
jupyter nbconvert --to rst examples/nmc-portal/L5TTPC2.ipynb
cp examples/sonata-network/sonata-network.rst docs/source/
cp -r examples/sonata-network/sonata-network_files docs/source/
cp examples/nmc-portal/L5TTPC2.rst docs/source/nmc-portal.rst
cp -r examples/nmc-portal/L5TTPC2_files docs/source/

This seems to work.

[AurelienJaquier]

Thanks @anilbey ! I implemented your changes and it seems to work now :)

[anilbey]

Good news :)

[anilbey]

Would it not work if we place the examples_to_rst.sh into either docs or examples and call it sh docs/examples_to_rst.sh in the .readthedocs.yaml?

[AurelienJaquier]

Yes, it should work. Let me implement it

[anilbey]

Brilliant, thanks a lot @AurelienJaquier