jupyterhub / jupyterhub/nbgitpuller

A refresher of the documentation system

Open
#251 0 comments 1 reaction 0 assignees View on GitHub
maintenance
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.