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

Add ability to build and map alternate documentation formats #70

Open samuel-emrys opened 3 years ago

samuel-emrys commented 3 years ago

Sphinx is capable of building documentation in a range of different formats detailed by sphinx.builders. It would be good to be able to support building and indexing all of these such that they are linkable via the widget. It's a feature that I really like about what readthedocs does. I'm personally only really interested in pdf, but here's a list of formats that might be useful:

Example of what I would like to be able to do with respect to the "Downloads" section:

rtd_downloads

If you can provide some advice on how this might be best implemented I might be able to allocate some time to implementing this.

Holzhaus commented 3 years ago

I implemented that for https://manual.mixxx.org over at @mixxxdj/manual by using the HTML context variables to construct a path.

samuel-emrys commented 3 years ago

Hi @Holzhaus , I'm not sure that's exactly the same thing. That requires you to independently and externally generate the pdf documentation. What I've implemented in PR #74 will use sphinx builders to generate the pdf version of the documentation at the same time as the html documentation for each version and make a link to that artefact available in the build context.

The "for each version" part of documentation generation is the hard part when it comes to creating artefacts, without essentially recreating everything that sphinx-multiversion already does - so I think that it has a place within the scope of sphinx-multiversion.

Unless you're integrating your pdf build with sphinx-multiversion in a way that I can't see?

samuel-emrys commented 2 years ago

@Holzhaus can you elaborate on how you're building the pdf documentation?