Fix doc buildsystem

[jougs]

This fixes #1660 by removing the custom Makefile for building the Sphinx documentation and integrates the documentation build process into the standard CMake build under the target html. I took the liberty to also update some pertaining files on the way. I still need to check if the changes still result in a successful build on Read the Docs.

[steffengraber]

The PyNEST examples are not created.
This is because the .rst files created by sphinx_gallery are no longer part of the source directory.
So the links in .../doc/examples/index.rst can not work anymore.

For the Models Directoy the same applies as for the PyNEST examples. The directory with the generated .rst files is not in the source directory. Sphinx cannot find it and generate the html files.

How about copying the doc/ directory with cmake into the build directory and using this as source for sphinx-build?

[jougs]

@steffengraber: I don't think I fully understand what you are saying (i.e. what do you mean by "not created"?).

Running make html locally, I see all PyNEST examples in <build_dir>/doc/html/examples/index.html just fine. The same is true for the model directory in <build_dir>/doc/html/models/index.html.

My recent commits also make the new conf.py work well on Read the Docs, and to me the result there also looks good.

Can you please be a bit more specific about the problem you are referring to?

[steffengraber]

In my case, both folders remained empty, even after several attempts. I will test your updates immediately.

[steffengraber]

Even after the updates I have no success and the two folders remains empty.
I tried it with a conda environment and without. Maybe others should try it as well.

@sarakonradi @terhorstd Could you test this?

[jougs]

That's really strange...

I get the following message at the end of the make html run, maybe this is related to your problem?

Sphinx-gallery gallery_conf["plot_gallery"] was False, so no examples were executed.

[jougs]

@steffengraber: with my recent changes, Sphinx should print doc_path, root_path and build_path right at the start. Could you please check if they contain reasonable values?

[steffengraber]

@jougs The paths are looking good:

build_path <myprefix>/build-nest
root_path <myprefix>/nest-simulator
doc_path <myprefix>/nest-simulator/doc

I will try again later in a clean system. The problem seems to be with me, if everything is ok on your system. Which python and sphinx versions do you have in use?

[jougs]

Sorry for causing confusion. What I meant is not that we have literally two README files (hence the quotes in my comment), but that we currently have similar/overlapping documentation workflow descriptions in two places:

1. doc/README.rst
2. doc/userdoc/documentation_workflow/user_documentation_workflow.rst

In my opinion this redundancy should be resolved by first merging the (updated) content of 1. into 2., updating 2. to iron out remaining inconsistencies, and then remove 1., or at least strip it down to just a link to 2. and convert it to MarkDown so it renders more nicely on GitHub (this is where the README.md above comes from. My brain apparently was already one step further when I wrote my last comment). Then happiness.

Could you please also indicate how you feel about my answers to your review comments by either resolving them, or by telling me what's still missing? Thanks!

[heplesser]

@jougs I fully agree with your suggestion on integrating 1 and 2. Keeping a minimal README.md with a link to the user_documentation_workflow document (straight to readthedocs?) seems very sensible to me.

And thanks for all the hard work!

[sarakonradi]

Hi! I have two more minor comments:

• The microcircuit image on the welcome page (doc/userdoc/index.rst) is broken
• The README link on the microcircuit landing page (doc/userdoc/examples/cortical_microcircuit_index.rst) is not working

@jougs Do you think you could have a look? Thanks for the many changes!

[jessica-mitchell]

Thanks @jougs I think this looks good

[jougs]

@sarakonradi: I've replaced the copytreeglob mechanism in doc/conf.py by explicit calls to shutil.copyfile in f0d9ffa. This solves the problem with the figures and the invisible README.rst at least for me. Can you please re-check? Thanks!

@heplesser, @jessica-mitchell: I've updated the documentation workflow documents and the README.rst in df5e4ea (as it was discussed above). Can you please have a look? More changes to the workflow documents are to come in #1926.

[heplesser]

@jougs This looks pretty good, I just discovered two glitches:

• If I click on the "README" link on .../install/share/doc/nest/html/examples/cortical_microcircuit_index.html, I just get to an empty page (.../install/share/doc/nest/html/examples/cortical_microcircuit.html)
• The image on the "User-level documentation workflow" page (![](file:///.../install/share/doc/nest/html/documentation_workflow/_static/img/documentation_workflow.png)) does not work. I do not understand why this happens because the file is there and I can open it with other software, just not with the browser (neither Safari nor Firefox). I wonder if macOS here is overly protective, so we can probably ignore this.

[jessica-mitchell]

Just a tiny typo, otherwise looks good. Many thanks @jougs

[jougs]

Apparently, something went wrong in the last commits. The rendered version on Read the Docs is currently empty. I'll investigate and create a fix for that now.

[hakonsbm]

@jougs Something went wrong with the .gitignore file too. Some of my dot-directories (such as .settings for Eclipse things and .vscode for VS Code things) are no longer ignored.

[heplesser]

@jougs Things look good on my Mac, building both user and developer docs (using @hakonsbm's branch for #1953).

[jougs]

@hakonsbm: This is caused by my removal of .* from .gitignore. I found that way too unspecific and having it prevented Git from picking up changes to .readthedocs.yml, .travis.yml and such. Would you please create a PR explicitly adding the things you want ignored to the corresponding section in the new .gitignore file? Thanks!

@heplesser: Yes, locally it works well. Unfortunately, the utterly black path magic to make Read the Docs, in-tree and out-of-tree documentation builds work from the same conf.py seems to be more fragile as I was hoping for. I'm working on a fix right now and will create another PR as soon as I have something.

Sorry for the inconveniences.