我可以在“阅读文档”中构建和托管自定义HTML页面吗？

Question

My program's documentation is mainly written in Sphinx , but it also includes two custom HTML pages:

• an example report produced by the program;
• an extended reference on certain features of the program.

These two HTML files are produced by the program itself, not by Sphinx.

I want to host my docs on Read the Docs , and it would be very convenient for me to build and host the two custom pages, versioned, together with the Sphinx docs.

My program is already installed in the RtD build environment as I have the Install Project option enabled. And since the RtD docs mention writing your own builder , I gather it might be possible to invoke my program from there and have it dump the HTML content in a specific place.

So I really have two questions:

1. Is this an appropriate use of Read the Docs? I guess it's not designed to host arbitrary Web pages — but then again, those files are not arbitrary, they are an important part of the docs.

2. How would I implement it? I'm having a hard time making sense of the RtD API : is this “builder” related in any way to Sphinx builders ? how do I hook it up to RtD? perhaps there is an example somewhere?

Answer 1

I achieved the desired result using Sphinx's html_extra_path feature:

A list of paths that contain extra files [...] They are copied to the output directory.

To generate these files, I haven't found a better place than right in my conf.py , which seems a bit precarious, but works so far. Of course, Install your project inside a virtualenv needs to be enabled in Read the Docs advanced settings.

Now my custom notices.html and showcase.html are treated just like the .html pages produced by Sphinx itself, with versioning and redirects: http://httpolice.readthedocs.io/page/notices.html