search

Holzhaus / sphinx-multiversion

Sphinx extension for building self-hosted versioned docs.
https://holzhaus.github.io/sphinx-multiversion/
BSD 2-Clause "Simplified" License
148 stars 65 forks source link

Custom build scripts #71

Open samuel-emrys opened 3 years ago

samuel-emrys commented 3 years ago

I've been looking for a way to add instructions to the build process aside from solely calling sphinx-build. As a C++ developer, my use case for sphinx involves using doxygen/breathe to generate API documentation prior to executing sphinx-build. I notice that you've got some instructions for exhale, which fills a similar role to what breathe does. Unfortunately, to generate an accurate API, both doxygen and breathe need to run prior to sphinx-build to ensure the API documentation is accurate for the branch that's being built. That is, it needs to run on every branch/tag that's being built.

Are you able to advise on whether there's currently a good way of achieving this, and if not, is there a good way to implement this?

My thought is that you could specify a script as an argument to sphinx-multiversion, at which point you allow a user to take full control of the build process. Any additional arguments could be passed to the script which could ignore them or parse them as required, but otherwise the process would depend on the script to make the appropriate sphinx-build calls.

samuel-emrys commented 3 years ago

I'm not sure how I missed this, but i think #62 will resolve this.

samuel-emrys commented 3 years ago

I've just realised that #62 doesn't resolve this entirely. I've made the suggestion there, but for further visibility/discussion (that PR doesn't have it's own issue), I think in addition to a pre-build command, a post-build command is required. In the cases where you might want to build alternate targets (i.e., pdf) sphinx builds intermediary .tex files, which can then be compiled to pdf using pdf-latex or similar. If PDF targets are desired, an additional command to compile the .tex files would be required. I'm not sure if this is the process for other build targets like epub3 for example. Relates to #70 .