Move docs Makefile up to project root and build docs there #3813
Conversation
There was a problem hiding this comment.
I agree having the source and output folders mixed together isn't ideal. I'd not gotten around to doing it, but I had previously thought about moving the build folder to the repo root, as an alternative to nesting everything a level deeper. (Having the build folder at repo root also has the advantage of making it clear there are gitignored leftovers in the working directory, when exploring the repo)
That said, zooming out a little the root problem here is that:
- really we shouldn't need a build directory to be created at all in development mode - but Sphinx doesn't have an in-memory mode
- sphinx-autobuild doesn't support cleaning up the output directory on exit automatically
- trapping the ctrl+C in
make livehtmland adding a remove step is possible, but kinda messy (from my brief SO glance just now)
I hate to say it but mkdocs solves all of these problems ;-)
Anyway for now, I'm leaning more towards moving the output directory to the repository root, since:
- I'm not keen on optimising the repo layout for tools rather than humans (nested reduces visibility)
- if we switch to mkdocs we'll only end up removing the nesting anyway
I'd be happy to move the Makefile to the repo root too, if that simplifies the current building the docs steps?
|
On a separate topic, perhaps we should switch to Markdown via a Sphinx plugin, so we can at least de-couple the RST vs Markdown and Sphinx vs mkdocs parts of the comparison? |
Different tools from different times ;-) That being said, all valid points! I'll remove the changes I made here so we return to |
|
@edmorley – I kept the |
edmorley
changed the title
* Remove coverage/local config entries, since they no longer exist. * Update the docs build output directory after #3813.
Since the port was changed in #3813 from 8000 to 8001 (presumably so it didn't clash with Virtualbox when run directly from the guest), however this broke running the docs from inside the VM (for those who don't want to install the docs dependencies on the host).
| @echo | ||
| @echo "Build finished. The HTML pages are in $(BUILDDIR)." | ||
|
|
||
| livehtml: | ||
| sphinx-autobuild -b html --poll $(SPHINXOPTS) $(BUILDDIR) | ||
| sphinx-autobuild -b html --poll $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR) -B -p 8001 |
There was a problem hiding this comment.
The port change broke docs serving from within Vagrant (I tend to run there to avoid installing the deps on the host); I've opened port 8001 in #3835. (And also updated the docs build directory path in .gitignore)
There was a problem hiding this comment.
Rather embarassingly the port part was an accidental check in! Thanks for fixing :)
Since the port was changed in #3813 from 8000 to 8001 (presumably so it didn't clash with Virtualbox when run directly from the guest), however this broke running the docs from inside the VM (for those who don't want to install the docs dependencies on the host).
This pushes the source RST files down into a separate directory so they don't live at the save level as the output folder. This is both in-keeping with how new Sphinx projects are laid out and aids separation of the two types of files. It has the bonus effect of making fuzzy searching better by not polluting results with built files.