Include files in Sphinx output on any path

Question

I have a project that I’m documenting where I’ve ended up with a structure like

docs/
conf.py
development/
    architecture.rst
    uimockups/
        index.html
        static/
            <supporting css and js files>
        mockup1/
            index.html
            ui1.html
            ui2.html
        mockup2/
            index.html
            ui1.html
            ui2.html

Where everything under uimockups is just a static site. For organizational reasons I really want to keep the folder structure as is here, and would like to just copy uimockups to build/development/uimockups directly, that way I could link to it from my architecture.rst file.

I’ve searched around online, but most of what I can find is pertaining to the _static folder for customizing CSS and that sort of thing. All I want is to copy this entire folder to its corresponding location in the HTML build output. Is this possible without writing a custom extension? Can sphinx perform this simple task through configuration alone?

Asked By: bheklilr

||

Source

Answer 1

Well, I figured out a solution, but it isn’t what I’d consider the best solution.

Since I wanted to be able to also do python -m http.server in the docs/development/uimockups folder and have it work, I ended up:

Renaming docs/development/uimockups/static to docs/development/uimockups/_static.
Changing all .html files to refer to files in ./_static or ../_static as appropriate instead of using an absolute /static path.
Adding 'development/uimockups' to the html_static_path variable in conf.py

This last step is the equivalent of adding cp development/uimockups/* $BUILD/_static/, so while not really ideal I end up with

$BUILD/
    _static/
        _static/     # From uimockups/
            <supporting files>
        index.html   # From uimockups/
        mockup1/
            ui1.html
            ui2.html
        mockup2/
            ui1.html
            ui2.html

Then I can link to this with `link text </_static/index.html>`_ in my rst files.

I don’t really like that I just have to shove this into the $BUILD/_static folder, and I can’t just have it appear in $BUILD/development/uimockups instead, but this doesn’t require me to write any code at least. It’s definitely not scaleable though, if I had multiple “static sub-sites” then they would potentially step on each other’s resources. One way to work around this would be to have

docs/
    development/
        uimockups-site/
            uimockups/
                index.html
                mockup1/
                mockup2/
                _static/

And then add development/uimockups-site to my html_static_path list so that the output is

$BUILD/
    _static/
        uimockups/
            index.html
            mockup1/
            mockup2/
            _static/

Answered By: bheklilr

Answer 2

You could add uimockups to html_extra_path in conf.py, and link to files in it as explained here.

Answered By: Pierre Carbonnelle

Include files in Sphinx output on any path

Question:

Answers: