Backlogged doc updates

[2bndy5]

Some docs updates that have accumulated.

Also (as part of the suggestions from #242 ) the hard-coded pytest CLI options have been moved from pyproject.toml to nox_file.py

resolves #162 resolves #190 resolves #234 resolves #242

[jbms]

Thanks!

[2bndy5]

I added a MyST example doc to satisfy #162. The MyST example doc is a bit raw, but it is meant to encourage further contributions by providing a foundation to build on. Apparently, the blocking factor to user contribution is that the original doc uses a private API (in myst_parser._docs module) to behave similarly to our rst-example directive. However, the myst-example directive relies on a div directive that is hidden elsewhere in the MyST ecosystem (probably not meant to be used publicly as well).

[jbms]

I added a MyST example doc to satisfy #162. The MyST example doc is a bit raw, but it is meant to encourage further contributions by providing a foundation to build on. Apparently, the blocking factor to user contribution is that the original doc uses a private API (in myst_parser._docs module) to behave similarly to our rst-example directive. However, the myst-example directive relies on a div directive that is hidden elsewhere in the MyST ecosystem (probably not meant to be used publicly as well).

I think our existing rst-example directive could easily be modified to support myst as well. In fact I think the only thing that needs to change is the language used for syntax highlighting, because when used from myst the nested_parse call will already do the right thing. (I think the div directive used by the myst-example directive defined by myst-parser comes from sphinx-design.)

[2bndy5]

I think our existing rst-example directive could easily be modified to support myst as well.

I had the same thought a while ago: https://github.com/jbms/sphinx-immaterial/issues/162#issuecomment-1303338182. But that was more geared toward converting rST to MyST on-the-fly and rendering both with the appropriate parsers.

[2bndy5]

I think the myst-example directive is more of a long-term and worthwhile goal. The solution here is only meant to satisfy #162 per user's request/feedback. I'm really just trying to close out as many docs-related issues with this PR.

[jbms]

I think the myst-example directive is more of a long-term and worthwhile goal. The solution here is only meant to satisfy #162 per user's request/feedback. I'm really just trying to close out as many docs-related issues with this PR.

Okay, sounds reasonable.