Generate DocSet using doc2dash

[mofeing]

I added some instructions for automatizing the DocSet generation, which is used in documentation apps like Dash and Zeal. It depends on doc2dash >= 2.4.1 which should be soon released and it fixed a problem I had when using doc2dash with quimb.

Should I add doc2dash >= 2.4.1 as a dependency for the docs extra requirements?

By the way, the site-location sidebar and the topbar unnecessarily take a significant amount of space in Dash, so I hide them with some CSS injection which I trigger with a nobars tag inside the conf.py:

https://github.com/mofeing/quimb/blob/9100da58321143532b27a8640107dff1dbdc0359/docs/conf.py#L178-L180

Thus, the html target has to be generated with the -t nobars flag. If you want to use the html documentation, the user has to rebuild it again. I added a note in the Makefile but I dunno if its something you like.

[codecov[bot]]

Codecov Report

Merging #108 (fb3a557) into develop (a54b22c) will not change coverage. The diff coverage is n/a.

@@           Coverage Diff            @@
##           develop     #108   +/-   ##
========================================
  Coverage    79.19%   79.19%           
========================================
  Files           39       39           
  Lines        15377    15377           
========================================
  Hits         12178    12178           
  Misses        3199     3199           

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update a54b22c...fb3a557. Read the comment docs.

[jcmgray]

Hi @mofeing, thanks and sorry to be slow getting to this! Have been taking a break for the first time in the while.

I haven't used doc2dash before and didn't fully understand, with this does one still generate the standard docs with

make html

? and then for doc2dash or vice versa, delete _build and regenerate with

make -t nobars html

one could always add a note here as well - https://quimb.readthedocs.io/en/latest/develop.html#building-the-docs-locally - for future reference.

[mofeing]

don't worry, there is no rush. hope you enjoyed your holidays!

Dash and Zeal already have a sidebar, and the docs' sidebars clutter the view. it hides the sidebars by using a lil bit of CSS injection which is only enabled if the -t nobars flag is present. make html still generates the normal documentation as mandated.

the way i coded it is that this flag is checked at the html rule of the Makefile, but i can create a new rule that creates the documentation at _build/html-nobars for example. doc2dash takes this documentation and generates the proper DocSet.

the idea is that this docset is automatically generated on each commit/release/... whatever. that way, Dash and Zeal could be feeded with an URL and automatically updated.

i'm still waiting to the doc2dash maintainer to merge the PR #104 and things can be better polished (rename names for the Dash view, the right sidebar is hidden but still uses space, ...), but it is functional.

---

without sidebars

with sidebars

[jcmgray]

I was going to suggest that a separate build target would be the cleanest option, and indeed looks like this is what you have gone for already - make html-docset? Let me know when this is ready to go!

[mofeing]

yep, in the end i considered that it is cleaner this way.

is there any chance that you agreed to automating the deployment with GitHub Actions? something like the build checks that are run on each PR. this way we can feed Dash with an URL and users would get the lastest documentation.

if so, would you like to run it on each release or on each commit to develop? normally the former is the recommended option but there are many diferences between the branch and the latest release.

finally, i'm waiting on hynek/doc2dash#104 to be merged. afterwards, we will be ready.

[jcmgray]

Sure I'd be happy to accept a github action that ran on each commit. However, I have not used Dash or github actions yet so would not set it up myself.

Doing more regular releases is definitely desirable, currently a v2 is just waiting on spending some time (which I don't currently have) on docs+tests to catch up with the functionality..

[mofeing]

great! dont' worry. that stuff is on me.

[mofeing]

So I've been checking out how to automatically upload the DocSet to Dash-User-Contributions and it seems a little more complicated than I thought. It can be done, but I prefer to merge this now, experiment with GitHub Actions and submit a PR later.

I've also document all the instructions from generating the DocSet to uploading it to the repo. Right now I will upload it manually.

Summarizing, I'm giving my OK for merging this.

[jcmgray]

Great, thanks very much!

At some point I was thinking of changing the theme to furo to match cotengra's new docs, in which case there might presumably be some css tweaks which I might try and ping you about.

[mofeing]

Kapeli/Dash-User-Contributions#3580 has been merged! Now all Dash users should be able to download the docs and use it. By the way, Dash prefers docs of stable releases (unless necessary) so I backported the changes to the 1.3.0 version and uploaded that version.