search

DiODeProject / MuMoT

Multiscale Modelling Tool - mathematical modelling without the maths
https://mumot.readthedocs.io/
GNU General Public License v3.0
21 stars 4 forks source link

Revert to using ReadTheDocs for building and serving docs #293

Closed willfurnass closed 5 years ago

willfurnass commented 5 years ago

Following on from https://github.com/DiODeProject/MuMoT/issues/179 I propose a switch back from Travis + GH Pages to ReadTheDocs (RTD) for building and serving rendered docs, as the issue that caused us to migrate away from RTD (failure to auto-generate API docs) has since been fixed by the RTD maintainers (https://github.com/rtfd/readthedocs.org/issues/4446).

Here's a test RTD build showing hyperlinked autogenerated API docs: https://mumot.readthedocs.io/en/latest/api.html (see also build info: https://readthedocs.org/projects/mumot/builds/)

@jarmarshall Are you happy for me to make this change? RTD is a much more versatile host for docs than GH Pages. Also, a move back to RTD allows us to side-step #243.

jarmarshall commented 5 years ago

Hi Will, this is very timely, as we are just finalising the manuscript and first release, and knowing where to point to for online documentation is quite important... As you seem confident this will work now, and is a better solution, please go ahead and move everything back... Thanks, James

willfurnass commented 5 years ago

@jarmarshall @tbose1 @joefresna Can you all sign up with ReadTheDocs to allow me to make you all co-maintainers of the MuMoT ReadTheDocs project?

jarmarshall commented 5 years ago

Thanks @willfurnass - I've just signed up via my GitHub account

joefresna commented 5 years ago

I did the same. Thanks.

tbose1 commented 5 years ago

I signed up as well

willfurnass commented 5 years ago

You should all now be able to administer the ReadTheDocs project via https://readthedocs.org/dashboard/mumot/.

ReadTheDocs integration now set up again, but it's now able to build the API docs.

jarmarshall commented 5 years ago

Great, thanks @willfurnass - just took a look and it looks like API and code navigation is now very easy...

jarmarshall commented 5 years ago

@willfurnass any idea why _round_to_1() shows up as a global function in the docs now? I believe it should be hidden, and there are lots of other functions with the same scope that are not picked up by Sphinx...

willfurnass commented 5 years ago

@jarmarshall I think you want to remove it from docs/source/api.rst.

jarmarshall commented 5 years ago

Just noticed that about() is missing at the package level too - is there a way to force a rebuild of that file, or does it need to be manually edited?

willfurnass commented 5 years ago

I'd add that to the function/class whitelist in docs/source/api.rst for now via a PR and we can investigate switching to a blacklist in future to minimise the chances of module/function/class/method info accidentally being excluded from the rendered docs.