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?
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:
docs/development/uimockups/static
to docs/development/uimockups/_static
..html
files to refer to files in ./_static
or ../_static
as appropriate instead of using an absolute /static
path.'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/