readthedocs
feature request: generate docsets (for DashDocs / Zeal / Velocity) server-side with `doc2dash`
I currently manually download docs from readthedocs and run doc2dash manually, locally. This is annoying because I have to manually enter the version number, redirect URL, et. al..
However, the invocation is pretty simple, and the fields are all things that readthedocs knows already; any project with an HTMLZip could have a docset almost automatically.
Would this be something you'd be interested in a contribution for?
Hi, I don't think we will be running this command in behalf of users, users should opt in into this, and for that, they should already be able to do this with https://docs.readthedocs.io/en/stable/build-customization.html or maybe even with the help of a sphinx extension that puts a link to download this generated file.
Also, looks like you can add the documentation of any projects via https://github.com/Kapeli/Dash-User-Contributions.
The rest of the core team may have a different opinion on this, so I'll keep this issue open.
Also, looks like you can add the documentation of any projects via https://github.com/Kapeli/Dash-User-Contributions.
That’s the whole point though: it’s a huge PITA to build a docset, because you have to clone the repo and figure out how to build the docs which each projects does slightly differently.
I for one would be already happy if RTD stopped shipping those weird single-page HTML docs for downloads and gave us a proper make html build that includes an objects.inv. That would already make everything much easier.
@glyph Hi! I'm not aware what DashDocs / Zeal / Velocity are. Can you expand a little more about what these are and what they are useful for? Besides, what would you like Read the Docs do?
@hynek reading this phrase confuses me a little
it’s a huge PITA to build a docset, because you have to clone the repo and figure out how to build the docs which each projects does slightly differently.
if projects have different build processes, how Read the Docs would know what are the exact commands it has to execute on each of them to generate the output expected for this feature? Is there a way to generate this command based on some particular settings?
@glyph Hi! I'm not aware what DashDocs / Zeal / Velocity are. Can you expand a little more about what these are and what they are useful for? Besides, what would you like Read the Docs do?
I presume this article of mine made him re-engage on this topic.
@hynek reading this phrase confuses me a little
it’s a huge PITA to build a docset, because you have to clone the repo and figure out how to build the docs which each projects does slightly differently. if projects have different build processes, how Read the Docs would know what are the exact commands it has to execute on each of them to generate the output expected for this feature? Is there a way to generate this command based on some particular settings?
What I'm talking about is what I get when I click the HTML button in the RTD pop up:
You get a single-page HTML download. Basically like a PDF document, just HTML.
I've just noticed there is actually an objects.inv in that archive and it can be converted, but the fact it's one huge HTML file makes it rather uncomfortable to work with once you try to read it.
@hynek thanks for the link and the explanation. I haven't read it completely, but I think I understand more or less what's the feature request and the expectations. It seems that "a new output format generated with doc2dash" for the documentation is requested.
As @stsewd mentioned in another comment, we don't automatically generate any output format. For PDF, HTMLZip and ePub documentation maintainers have to opt-in. So, I don't think it makes sense to automatically run doc2dash behind the scenes for them.
Since Read the Docs supports "Builds customization", I think the proper approach here is to encourage authors to generate and upload the docset using Dash API. I think something like the following would work:
# .readthedocs.yaml
build:
jobs:
post_build:
- pip install doc2dash
- doc2dash --output my-project.zip --source docs/_build/html
- curl -X POST -d my-project.zip -H "Token: ${DASH_TOKEN}" https://api.dash.com/upload/docset
NOTE that these commands are placeholders showing the idea of the workflow, but they are not valid
I think that should be enough to solve this problem and it will reduce the work required from Dash users. If you know the exact commands required to be executed, I'm happy to add a section in our documentation explaining how to do this. I'd say it perfectly fits under https://docs.readthedocs.io/en/stable/build-customization.html#build-jobs-examples
For PDF, HTMLZip and ePub documentation maintainers have to opt-in
In some sense I guess this is true, but practically speaking formats: all is the default, so formats are opt-out, not opt-in. I know because I just did this: https://github.com/twisted/twisted/pull/11646/files
I think the proper approach here is to encourage authors to generate and upload the docset using Dash API
This is definitely a good idea for a start, but I specifically want to get this integrated into RTD's default pipeline so that docsets will be broadly available for projects which fit into the happy path / default configuration for most RTD sphinx projects.
the proper approach here is to encourage authors
As an owner of a service, that certainly looks like the proper approach. For me as a FOSS maintainer, that is an encouragement for pestering everyone whose software I'm using.
For PDF, HTMLZip and ePub documentation maintainers have to opt-in
In some sense I guess this is true, but practically speaking
formats: allis the default, so formats are opt-out, not opt-in. I know because I just did this: https://github.com/twisted/twisted/pull/11646/files
Was going to say, given the preponderance of documentation with all formats enabled, I had serious doubts as to how many actually choose to opt in. The default option as it currently stands translates to "take care of this for me". Adding a new format that ReadTheDocs takes care of for documentation authors... feels entirely appropriate.
As I mentioned in a previous comment, project maintainers can opt-in to build this output format by using build.jobs or build.commands and exposing this format to their users. Given the complexity that it would be to add and maintain another format in the core of Read the Docs, I don't think we will be able to implement this feature in the near future.
With the introduction of the new addons (see https://blog.readthedocs.com/addons-flyout-menu-beta/), users exposing this format will be able to customize the flyout to show the doc2dash format in the flyout if they want to.
Because of these reasons, I'm going to close this issue. We can revisit in the future and re-evaluate our roadmap.