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]

I believe pip install -e also does the npm build automatically. Is that not correct?

[2bndy5]

No, we had someone ask recently why sphinx failed to find the static bundles when it was using an editable install.

#238 (comment)

[jbms]

Looks like the issue is that pip install -e . no longer runs the develop command, which is what we were relying on in setup.py to do the nodejs build. It looks like there is a new mechanism that can be used to handle editable builds, but it is not clear to me exactly how to use it:

https://setuptools.pypa.io/en/latest/userguide/extension.html#supporting-sdists-and-editable-installs-in-build-sub-commands

[2bndy5]

I honestly don't mind the way it works now. It cuts down on the initial editable install time significantly.

Although, I do understand the convenience for newcomers not having to remember the npm build step. Should this become a separate issue?

[jbms]

I created an issue. You don't need to re-run pip install -e . that often -- that is, after all, the whole point of an editable install. So I think it is definitely desirable for it to just work by default.

[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: #162 (comment). 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.