Add MyST-Parser and link community files in docs sidebar by julianz- · Pull Request #835 · cherrypy/cheroot

julianz- · 2026-07-05T21:29:08Z

Add myst-parser to docs dependencies and Sphinx extensions, enabling Markdown support. Link the Code of Conduct and License in the docs sidebar as an initial test of the integration.

❓ What kind of change does this PR introduce?

📋 What is the related issue number (starting with #)

Resolves #

❓ What is the current behavior? (You can also link to an open issue here)

❓ What is the new behavior (if this is a feature change)?

📋 Other information:

📋 Contribution checklist:

(If you're a first-timer, check out
[this guide on making great pull requests][making a lovely PR])

codecov · 2026-07-05T21:32:18Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.19%. Comparing base (3937fe1) to head (51963cf).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #835   +/-   ##
=======================================
  Coverage   78.19%   78.19%           
=======================================
  Files          41       41           
  Lines        4788     4788           
  Branches      547      547           
=======================================
  Hits         3744     3744           
  Misses        905      905           
  Partials      139      139

webknjaz · 2026-07-07T14:45:38Z

Need to decide how to deal w/ https://github.com/cherrypy/cheroot/actions/runs/28755500504/job/85261942391#step:16:82. I think where were a few toggles in the Sphinx config. One way could be cutting the doc on inclusion. I'd need to check how I used to handle this in other places but if you want to look, the solution is probably in one of sphinx-contrib/towncrier, ansible/pylibssh, ansible/awx-plugins or jazzband/pip-tools.

webknjaz · 2026-07-07T14:47:54Z

 furo
+myst-parser
 sphinx-issues  # Sphinx roles providing support for linking GitHub
 sphinxcontrib-apidoc >= 0.3.0


For the future: modern versions of Sphinx can do this natively, we should try to migrate some day.

Good to know.

webknjaz · 2026-07-07T14:48:38Z

@@ -0,0 +1,3 @@
+Added ``myst-parser`` to enable Markdown support in Sphinx documentation,


I think sphinx-issues provides a :pypi: role. Let's try it out:

Suggested change

Added ``myst-parser`` to enable Markdown support in Sphinx documentation,

Added :pypi:`myst-parser` to enable Markdown support in Sphinx documentation,

webknjaz · 2026-07-07T14:49:24Z

@@ -0,0 +1,3 @@
+Added ``myst-parser`` to enable Markdown support in Sphinx documentation,
+and linked the Code of Conduct and License in the docs sidebar


We could also reference said docs via relevant Sphinx roles.

webknjaz · 2026-07-07T14:54:18Z

+   Code of Conduct <code_of_conduct>
+   License <license>


Instead of putting these on the top-level, have the docs under the contrib dir. Just like the guidelines above.

Also, no need to add explicit titles in two places if they don't differ.

webknjaz · 2026-07-07T14:56:49Z

@@ -0,0 +1,4 @@
+# License


This breaks the docs build: https://app.readthedocs.org/projects/cheroot/builds/33450467/#328554371--132. There's even not PR preview because the build doesn't complete.

webknjaz · 2026-07-07T14:57:03Z

Is this a symlink? No need to do this. Use the Sphinx-native include role like https://github.com/ansible/pylibssh/blob/0efb3df9a8f1a32ba7ac0c4ee073b950481e0527/docs/contributing/code_of_conduct.rst?plain=1#L1 / https://github.com/ansible/awx-plugins/blob/7c6a7cf97ec1e2ed3c36c0dd2e0dbb29436dea78/docs/contributing/code_of_conduct.md?plain=1#L1

webknjaz · 2026-07-07T14:59:37Z

 sphinx-tabs >= 1.1.0

 furo
+myst-parser


I've started annotating the direct dep additions w/ their purpose in other projects

Suggested change

myst-parser

myst-parser[linkify] # Markdown documents support w/ in-text link detector

webknjaz · 2026-07-07T14:59:49Z

    'sphinx.ext.intersphinx',
    # Third-party extensions:
    'jaraco.packaging.sphinx',
+    'myst_parser',


Suggested change

'myst_parser',

'myst_parser', # extended markdown; https://pypi.org/p/myst-parser

webknjaz · 2026-07-07T15:04:51Z

I'm not entirely sure we should be rendering the license text in the docs. A lot of projects just have it in the packaging metadata + GH. But if you fix the build, we could see how it renders, I suppose.
Otherwise, I'd just postpone. Having CoC included should be enough to test how MyST-Parser integrates and would give us the build infra for adding more Markdown separately w/o having to think about the configuration bits.

webknjaz · 2026-07-07T15:07:47Z


  # local
  "furo",
+  "myst-parser",


Let's not include this change. I think we should be able to get rid of the docs extra here as it's an ancient leftover. Try doing so in a separate PR to see if anything depends on this docs extra.

webknjaz · 2026-07-07T16:08:07Z

I think #828 should be completed first to reduce the amount of noise in CI as it's difficult to sort through the unrelated failures otherwise.

read-the-docs-community · 2026-07-07T20:16:23Z

Documentation build overview

📚 cheroot | 🛠️ Build #33485766 | 📁 Comparing 51963cf against latest (3937fe1)

🔍 Preview build

3 files changed

+ contributing/code_of_conduct/index.html
± history/index.html
± pkg/cheroot.server/index.html

Add myst-parser to docs dependencies and Sphinx extensions, enabling Markdown support. Link the Code of Conduct in the docs sidebar as an initial test of the integration.

webknjaz · 2026-07-12T21:40:28Z

@@ -0,0 +1,3 @@
+Added :pypi:`myst-parser` to enable Markdown support in Sphinx documentation,
+and linked the Code of Conduct in the docs sidebar


Can we make that Code of Conduct a link? Would a :ref: work? Or something similar?

@julianz- as an alternative, this should work

Suggested change

and linked the Code of Conduct in the docs sidebar

and linked the :doc:`Code of Conduct <contributing/code_of_conduct>` in the docs sidebar

webknjaz · 2026-07-12T21:42:56Z

   :hidden:

   contributing/guidelines
+   contributing/code_of_conduct


I didn't realize the CoC doc title was so long. Let's make the sidebar link shorter for now and maybe improve it later if needed.

Suggested change

contributing/code_of_conduct

Code of Conduct <contributing/code_of_conduct>

Sure. I also renamed "Private (dev) API autodoc" to "Internal API" in the sidebar as I thought the old name looks quite clunky. Happy to revert or use a different label if you prefer something else.

I'm not sure about the internal API. This isn't in the scope of the PR and I'm also not sure how to name it. That name might be long but it's clear that it's not for public consumption and it just a dump of something generated w/o careful curating. Maybe, once we get to documenting the public API and pick the public and private bits apart, into different sections, it'll make sense to thing of better naming as a part of that move.

Calling it "Private" though seems counter intuitive. It's the whole API currently no?

psf-chronographer Bot added the bot:chronographer:provided A mark meaning that a new change log entry is present within the patch. label Jul 5, 2026

julianz- mentioned this pull request Jul 5, 2026

Update contribution guidelines in pull request template #834

Merged

16 tasks

webknjaz reviewed Jul 7, 2026

View reviewed changes

julianz- force-pushed the add-myst-parser branch from 4d6933a to cae4f43 Compare July 7, 2026 20:15

julianz- force-pushed the add-myst-parser branch from cae4f43 to c04a946 Compare July 7, 2026 20:18

Add MyST-Parser and link Code of Conduct in docs sidebar

51963cf

Add myst-parser to docs dependencies and Sphinx extensions, enabling Markdown support. Link the Code of Conduct in the docs sidebar as an initial test of the integration.

julianz- force-pushed the add-myst-parser branch from c04a946 to 51963cf Compare July 7, 2026 20:44

webknjaz reviewed Jul 12, 2026

View reviewed changes

		@@ -0,0 +1,3 @@
		Added ``myst-parser`` to enable Markdown support in Sphinx documentation,

	Added ``myst-parser`` to enable Markdown support in Sphinx documentation,
	Added :pypi:`myst-parser` to enable Markdown support in Sphinx documentation,

		@@ -0,0 +1,3 @@
		Added ``myst-parser`` to enable Markdown support in Sphinx documentation,
		and linked the Code of Conduct and License in the docs sidebar

	myst-parser
	myst-parser[linkify] # Markdown documents support w/ in-text link detector

	'myst_parser',
	'myst_parser', # extended markdown; https://pypi.org/p/myst-parser

		@@ -0,0 +1,3 @@
		Added :pypi:`myst-parser` to enable Markdown support in Sphinx documentation,
		and linked the Code of Conduct in the docs sidebar

	and linked the Code of Conduct in the docs sidebar
	and linked the :doc:`Code of Conduct <contributing/code_of_conduct>` in the docs sidebar

	contributing/code_of_conduct
	Code of Conduct <contributing/code_of_conduct>

Uh oh!

Uh oh!

Conversation

julianz- commented Jul 5, 2026

Uh oh!

codecov Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

webknjaz commented Jul 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

webknjaz Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

webknjaz commented Jul 7, 2026

Uh oh!

read-the-docs-community Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented Jul 5, 2026 •

edited

Loading

webknjaz Jul 7, 2026 •

edited

Loading

read-the-docs-community Bot commented Jul 7, 2026 •

edited

Loading