[Python-Dev] RFC: New/update the Docs Sphinx theme: responsive, edit page links,

[Wes Turner]

Where would be the best place to discuss or just improve the CPython docs sphinx theme? What would Python need in a {PyData,} Sphinx theme fork:

- [ ] ENH: add <edit on github> links to every docs page

- [ ] ENH: responsive breakpoints for mobile devices

- [ ] ENH: responsive fonts

- [ ] ENH: toggle-able dark theme

- [ ] ENH: interactive code examples (in WASM with pyodide like JupyterLite)

- [ ] ENH?: Two sidebars: {Global TOC} {Content} {Document TOC}

The PyData theme [bandwagon, feature justification, maintenance burden justification]

Src: https://github.com/pydata/pydata-sphinx-theme

Docs: https://pydata-sphinx-theme.readthedocs.io/en/latest/

```quote

Other sites that are using this theme:

- Pandas: https://pandas.pydata.org/docs/
- NumPy: https://numpy.org/doc/stable/
- SciPy: https://scipy.github.io/devdocs/
- NetworkX: https://networkx.org/documentation/latest/
- Bokeh: https://docs.bokeh.org/en/latest/
- JupyterHub and Binder: https://docs.mybinder.org/, http://z2jh.jupyter.org/en/latest/, https://repo2docker.readthedocs.io/en/latest/, https://jupyterhub-team-compass.readthedocs.io/en/latest/
- Jupyter Book beta version uses an extension of this theme: https://beta.jupyterbook.org
- Fairlearn: https://fairlearn.org/main/about/

```

The sphinx-book-theme theme (Jupyter Book theme) has a few possibly necessary features for the {CPython, Devguide, *} docs:

https://github.com/executablebooks/sphinx-book-theme

https://sphinx-book-theme.readthedocs.io/en/latest/ ::

```quote

A Sphinx theme with a clean design, support for interactive content, and a modern book-like look and feel.

Flexible content layout: Inspired by beautiful online books, such as the Edward Tufte CSS guide

Visual classes designed for Jupyter Notebooks: Cell inputs, outputs, and interactive functionality are all supported.

Launch buttons for online interactivity: For pages that are built with computational material, connect your site to an online BinderHub for interactive content.

Bootstrap 4: To style visual elements and add functionality.

International: All text integrated in the theme is translated to the specified Sphinx language.
```

https://github.com/python/cpython/blob/main/Doc/conf.py#L68 :

```python

html_theme = 'python_docs_theme'

```

https://github.com/python/cpython/blob/main/Doc/requirements.txt#L12
```

# The theme used by the documentation is stored separately, so we need
# to install that as well.
python-docs-theme

```

Pypi: https://pypi.org/project/python-docs-theme/

Src: https://github.com/python/python-docs-theme/

What are some better ways to add {Source RST, Source, Edit, History, and Annotate} links to every sphinx doc page than sphinxcontrib-srclinks?

https://github.com/westurner/sphinxcontrib-srclinks#usage

- sphinxcontrib-srclinks: Source RST, Source, Edit, History, and Annotate, Clone URL

  - [ ] copy clone URL to clipboard button

- pydata-theme: 'Edit this page' on the document TOC sidebar

- sphinx-book-theme: {gh, bb, gl} icon > 'Suggest edit'

- [ ] ENH: add collapsible sidebar to whatever is chosen as a suitable replacement for the current non-responsive theme

[Senthil Kumaran]

Replying to Python-Dev. I hope you found the list and got feedback from
the documentation maintainers. Python devguide
https://devguide.python.org/ was using an updated theme, and I assume
that docs will get updated soon a responsive. There have been plenty
discussions on this front.


Thank you,
Senthil
_______________________________________________
Python-Dev mailing list -- pytho...@python.org
To unsubscribe send an email to python-d...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at https://mail.python.org/archives/list/pytho...@python.org/message/XIJ7KMLDAVMVCGILH5TJY2IPOANV7TW6/
Code of Conduct: http://python.org/psf/codeofconduct/