jupyterhub / jupyterhub/nbgitpuller
A refresher of the documentation system
- Dominant language
- Python
- Stars
- 237
- Forks
- 86
- PR merge metrics
- No merged PRs in 30d
Description
- Transition to 100% MyST
- Cleanup the sphinx `conf.py` file
- Reduced complexity by stripping LaTeX/PDF/HTMLHelp build configurations
- Remove other configurations that aren't used but just part of a boilerplate, for example some version specification hardcoded in `conf.py`
- Example configurations: [z2jh](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/main/docs/source/conf.py)
- Update our Makefile commands to include
- `make devenv` - a command to start up an automatically refreshing-on-changes kind of local webserver
- `make linkcheck` - a command to check links being valid
- Example configurations: [z2jh](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/main/docs/Makefile)
- Add relevant GitHub CI integration:
- Run `make linkcheck`
- Example configurations: [z2jh](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/main/.github/workflows/test-docs.yaml)
- Add relevant `pre-commit-config`
- `prettier` for markdown formatting (and formatting of embedded Python code block)
- Example configurations: [z2jh](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/main/.pre-commit-config.yaml)
Contributor guide
Research direction
Start by inspecting the documentation conf.py and Makefile, then compare the linked z2jh examples for the development server and link checking. Review the relevant .github workflow and .pre-commit-config configuration before making changes. Done means the docs use MyST, local serving and link checks work, CI runs linkcheck, and the listed formatting checks are configured.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, markdown, python
- Domain
- build-system, ci-cd, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100