documentation improvements

[stephanlachnit]

First of all thanks for this awesome project, it really helped me a lot.

I'm currently working on getting symfit in the official Debian archives. One thing that gave some headache was the documentation though. In Debian, all Python packages / libraries should contain an optional offline documentation.

To begin with, currently when generating the html output, all pictures in docs/_static are also copied to docs/_build/_static, because html_static_path is falsely set to that. It isn't intended for for pictures that are mentioned in the rst files, rather stuff like css files where this doesn't apply. Pictures that are mentioned in the rst files will automatically be copied to docs/_build/_images, and this is where the html files actually reference to.

The second thing I noticed was that every rst file is copied to docs/_build/_sources. The html pages link to these files as "view source file", however I found that more distracting because a) it isn't the Python code as one might expect, and b) the image paths are wrong. So I disabled that.

I actually noticed the third thing just by chance. The default html theme isn't actually the default. The default theme is alabaster, which looks way better IMHO, and probably also works better on tablets and stuff. Commenting the setting will use sphinx' default theme (but not the default theme, which in fact is the classic theme).

Something that isn't strictly necessary but I think a good idea is documenting mathjax_path. It took me quite a while to find this variable, so I think it's helpful to mention the variable. What it does is allowing to define a path to MathJax.js, instead of using a link to load the script. This is required for a proper offline documentation.

Also something that I would recommend: setting the .doctrees dir outside of _build. This has two advantages: 1) it keeps _build clean, i. e. when building html there are basically only required files in _build, meaning the documentation can be deployed by simply copying the entire folder 2) .doctrees can be cached, so deleting _build won't delete that cache

There also some other stuff I will look into (for me the tests are failing and there are some warnings in the documentation, giving away the full build path).

[tBuLi]

I'm glad to hear you like this project, and thank you for giving back! It's good to see you are trying to add this to the Debian archives, so whatever you need.

I've looked at your changes and don't see any reason not to merge this. If I understand the mathjax comment correctly then you just want to have it in the config though commented out in case you ever need it, or do you need it active?

[stephanlachnit]

If I understand the mathjax comment correctly then you just want to have it in the config though commented out in case you ever need it, or do you need it active?

Yes exactly. It isn't strictly necessary to have this commented, but I took me quite a while to figure it out, so maybe it will help other people doing the same.

I've looked at your changes and don't see any reason not to merge this.

I just noticed there is another option I would put in there, so maybe don't merge it yet.

[tBuLi]

I'll wait until you are happy with it, just let me know when it can be merged :)

[stephanlachnit]

I'll wait until you are happy with it, just let me know when it can be merged :)

Just one more option (nbsphinx_requirejs_path), basically the same as with mathjax_path. I don't think I have anything to add (for now).

[tBuLi]

Does that mean you would be happy for this to be merged? :)

[stephanlachnit]

Does that mean you would be happy for this to be merged? :)

Yep :)