Skip to content

Add tooling to create Dash docset for RSMTool and other minor changes. #375

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
Parent: Merge `master` into `stable`.
merged 21 commits into from
Feb 21, 2020
Merged

Add tooling to create Dash docset for RSMTool and other minor changes. #375

merged 21 commits into from
Feb 21, 2020

Conversation

@desilinguist
Copy link
Collaborator

@desilinguist desilinguist commented Feb 20, 2020 •
edited
Loading

This PR adds the tooling to create an RSMTool docset for the Dash app on macOS as per #357. Dash is an offline documentation browser that integrates with basically every IDE/editor out there and has docsets for pretty much any major open-source project under the sun. I use it heavily during development as do many other macOS folks. In addition to the Dash stuff, it also makes some other minor changes (listed below).

This PR:

  1. Adds the underlying machinery to make generating the Dash docset as easy as running make dash in the doc directory.
  2. Adds instructions on how to then make that docset make available to the general public.
  3. Adds notes to the repo README, the contributing guidelines, as well as the main page of the documentation to publicize that we (will) have such a docset available.
  4. Cleans up unused options in doc/conf.py.
  5. Fixes some issues with links, indentations, and newlines that sphinx was complaining about.
  6. Moves the static assets (images and the paper PDF) under assets and updates the documentation and doc/conf.py.
  7. Modifies doc/conf.py to automatically add the current year as opposed to us needing to manually update it every year.
  8. Excludes the recently added deprecated_positional_argument() decorator from sphinx-autodoc.

Notes:

  • Dash docset uses a different theme (Alabaster) since the RTD theme uses its own sidebar which looks weird since Dash has its own sidebar.
  • Dash is a paid app but there's an open-source alternative called Zeal that works with Dash docsets.

To see what this docset looks like in Dash, take a look at this video.

@desilinguist
Add script to insert Dash TOC anchors in HTML files.
59e78c0
@desilinguist
Add doc2dash to requirements.
ee5c6a6
@desilinguist
Add icon for dash docset
1be0c0b
@desilinguist
Exclude deprecated_positional_argument() method from autodoc.
86dfab7
@desilinguist
Clean up doc/conf.py
f88e1cc 
- Remove unused options.
- Make it so that the copyright year is automatically updated.
- Add missing exclusion.
- Add support for Dash docset building.
@desilinguist
Add Dash docset building to Makefile.
45a4275
@desilinguist
Fix broken link.
2365a08
@desilinguist
Fix some indentation issues.
74d8e7e
@desilinguist
Add instructions for Dash docset building
4d14919 
- Create separate `internal` folder that contains these and the release process document that was at the top level before.
@desilinguist
Add notes about Dash to repo README and documentation.
90a282d
@desilinguist
Tweak dash instructions.
1084adf
@desilinguist
Reorganize static assets
1e27fe8 
- Move images and PDF to new `assets` folder.
- Tell sphinx about `assets` folder via `html_static_path`.
@desilinguist
Add comment to conf.py.
ac61643
@desilinguist
Tweak Dash message.
2971425
@desilinguist
Remove extra line.
82f72d0
@desilinguist
Merge branch 'fix-broken-rtd-builds' into integrate-dash
7d264cb
@desilinguist
Add note about dash to contributing section.
631d96a
@desilinguist
Merge branch 'master' into integrate-dash
839ddb7
@desilinguist
Fix ref link
e8e621d
@desilinguist
Fix filepath
f255800
@pep8speaks
Copy link

pep8speaks commented Feb 20, 2020 •
edited
Loading

Hello @desilinguist! Thanks for updating this PR.

Line 961:101: E501 line too long (142 > 100 characters)

Comment last updated at 2020-02-21 14:00:37 UTC

@desilinguist desilinguist linked an issue Feb 20, 2020 that may be closed by this pull request
Create a version of the documentation for the Dash app #357
Closed
@coveralls
Copy link

coveralls commented Feb 20, 2020 •
edited
Loading

Coverage Status

Coverage remained the same at 91.837% when pulling daba121 on integrate-dash into b3611cf on master.

@aloukina
Copy link
Collaborator

Thank you for the video!

aloukina
aloukina approved these changes Feb 20, 2020
View reviewed changes
Copy link
Collaborator

@aloukina aloukina left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me!
I am slightly concerned that it adds extra overhead to the release process but we can over time whether we feel that the benefits overweigh that.

doc/add_dash_anchors.py
from bs4 import BeautifulSoup

# pre-define the list of HTML files we want to miodify
FILES_TO_MODIFY = ["advanced_usage.html", "api.html", "contributing.html",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do we make sure this list is up-to-date? Can we create it automatically based on directory content?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I tried this but struggled with it. There are some auto-generated HTML files that we do not want to add Dash nchors to (for example, genindex.html). I haven’t been able to figure out if this set is fixed and so we can just include all files except the ones in this set. I can work on this in the future.

@desilinguist
Copy link
Collaborator Author

I am slightly concerned that it adds extra overhead to the release process but we can over time whether we feel that the benefits overweigh that.

That’s fair enough. I’ll try to figure out how to automate this as much as possible as we go forward.

mulhod
mulhod approved these changes Feb 21, 2020
View reviewed changes
Copy link
Contributor

@mulhod mulhod left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. I generated the dash documentation myself and can peruse the contents in my local _build directory. The changes look good to me too.

@desilinguist desilinguist merged commit 11326bb into master Feb 21, 2020
@delete-merged-branch delete-merged-branch bot deleted the integrate-dash branch February 21, 2020 16:52
srhrshr pushed a commit to srhrshr/rsmtool that referenced this pull request Oct 23, 2021
@desilinguist
Merge pull request EducationalTestingService#375 from EducationalTest…
d10030a 
…ingService/integrate-dash

Add tooling to create Dash docset for RSMTool and other minor changes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@aloukina aloukina aloukina approved these changes

+1 more reviewer

@mulhod mulhod mulhod approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Create a version of the documentation for the Dash app

5 participants

@desilinguist @pep8speaks @coveralls @aloukina @mulhod