Skip to content
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.

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

Simplify and enhance using examples in documentation #218

Closed
3 tasks
mikemckiernan opened this issue Apr 18, 2022 · 1 comment
Closed
3 tasks

Simplify and enhance using examples in documentation #218

mikemckiernan opened this issue Apr 18, 2022 · 1 comment
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@mikemckiernan
Copy link
Member

The naive approach in 22.04 for repurposing the example notebooks was to copy the examples directory into the Sphinx source directory and build. This simple approach was OK for some repositories and not OK for many.

The major downside for examples directories that have subdirectories, is that we needed to use README.rst with toctree directives or the notebooks were orphaned from the navigation. Using RST is too inconvenient and we need a way to repurpose the README.md files that already exist.

After evaluating AutoStructify and sphinx-external-toc, I think the better choice is to use sphinx-external-toc.

  • Change all repos to use sphinx-external-toc.
  • Change all repos to use a fork of sphinx-multiversion so that recent tagged releases can use sphinx-external-toc as well.
  • Add sphinxcontrib-copydirs to all repos so that examples are copied into the Sphinx source directory and that images are copied from the examples directory (and subdirectories) into the Sphinx build output.
@karlhigley karlhigley added the documentation Improvements or additions to documentation label Apr 18, 2022
@mikemckiernan
Copy link
Member Author

mikemckiernan commented Apr 19, 2022

Merlin

Systems

Models

  • push docs-ext-toc to fork and clobber main
  • push v0.2.0-docs and v0.3.0-docs to fork
  • confirm docs-sched-rebuild builds
  • push v0.2.0docs and v0.3.0-docs upstream
  • open PR

Core

NVTabular

  • push docs-ext-toc to fork and clobber main
  • push v0.10.0-docs, v0.11.0-docs, v0.7.1-docs, v0.8.0-docs, v0.9.0-docs, v1.0.0-docs to fork
  • confirm docs-sched-rebuild builds
  • push v0.10.0-docs, v0.11.0-docs, v0.7.1-docs, v0.8.0-docs, v0.9.0-docs, v1.0.0-docs upstream
  • open PR

HugeCTR

  • push docs-rn to fork and clobber main
  • push v3.5-docs to fork
  • confirm docs-sched-rebuild builds
  • push v3.5-docs upstream
  • open MR

T4R

  • push docs-ext-toc to fork and clobber main
  • push v0.1.2-docs, v0.1.3-docs, v0.1.4-docs, v0.1.5-docs, v0.1.6-docs, v0.1.7-docs to fork
  • confirm docs-sched-rebuild builds
  • push v0.1.2-docs, v0.1.3-docs, v0.1.4-docs, v0.1.5-docs, v0.1.6-docs, v0.1.7-docs to upstream
  • open PR

dist-embed

  • push docs-ext-toc to fork and clobber main
  • confirm docs-sched-rebuild builds
  • open PR

template

  • push docs-ext-toc to fork and clobber main
  • confirm docs-sched-rebuild builds
  • open PR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants