mystmd

[thewtex]

• docs: create myst.yml
• docs: run myst init --write-toc
• docs: toc tweaks
• docs: add dark logo
• docs: packages pagee myst re-formatting

[thewtex]

@agoose77 @rowanc1 @stevejpurves

[thewtex]

@agoose77 the docs have been converted to myst 🎉 🌮 less the api-docs. I am wondering if you have implemented any of the py:obj etc. directives yet before I go about it.

[agoose77]

Hi @thewtex, this is cool!

I'm currently working on a Sphinx plugin that generates MyST AST. The idea is that we would then natively embed this into a MyST-MD project. I think this won't use the same mechanism as the embed directive, because otherwise we won't be able to link from the non-Sphinx project into the Sphinx project.

I have already tested it on your documentation, which is really exciting!

We have a MyST developers meeting today at 3 PM BST. You'd be welcome to attend, although I suspect we won't be able to add much more than my discussion here just yet. In that meeting, though, we'll discuss next-steps for this work to figure out how best to tie it in to MyST-MD as a whole

[thewtex]

@agoose77 thanks for the note! Sorry I missed the meeting. Any other thoughts on next steps?

[agoose77]

Next steps are really all on our side. I'm building this out to work as nicely as possible. Here's the latest screenshot: https://discord.com/channels/1083088970059096114/1177359316886503464/1263870267604729876

[thewtex]

@agoose77 thanks for the update. That discord link is not working for me. Any links to code 👨‍💻 📖 😄 ?

[agoose77]

Does this work? https://discordapp.com/channels/1083088970059096114/1177359316886503464/1264226046769631363

[thewtex]

This is what I get:

[agoose77]

Huh, maybe you need to join the discord first. In any case:

Will need to do a pass to see what's not working, but:

• 🧙 Render new nodetypes for Sphinx autodoc jupyter-book/myst-theme#431 (themeing PR)
• 🐱 Add support for pre-parsed mdast-type files (.myst.json) jupyter-book/mystmd#1398 (CLI loading of .json files)
• https://github.com/executablebooks/sphinx-ext-mystmd (generating mdast from sphinx via myst builder)
• 📂 Drop folders in pattern expansion jupyter-book/mystmd#1399 (flatten pattern expansion)

[agoose77]

A small update -- we've merged in some of these PRs (into mystmd), making it easier to get started. To try this out, you'd need to

1. Build mystmd from its main branch (follow the development guide).
2. Modify your conf.py to pull in sphinx_ext_mystmd from GitHub, and remove any other extensions that aren't required for the API docs
3. Modify conf.py to only build the apidocs, e.g.

   exclude_patterns = [".venv", '_build', 'Thumbs.db', '.DS_Store', "cxx", "development", "introduction", "model", "myst", "python", "static", "typescript"]

4. Run sphinx-build with the new myst builder (sphinx-build -b myst . ./myst)
5. Run myst start (using the new build of myst) in headless mode (so we can use a newer theme), i.e. myst start --headless
6. Build the myst-theme PR and run the book theme npm run theme:book

[thewtex]

join the discord first.

I believe I tried to do this at some point, but I received a notice that it was only available for free for students at academic institutions or similar, which is not accessible to me. And I am not sure how to get that prompt up again.

A small update

Big update! Outstanding work, @agoose77 !

As I mentioned in the airport, I would like to forgo Sphinx altogether. As I understand it, the approach that you are taking is more general and provides a workable solution for other projects that are not necessarily using autodoc2. I will still need to write a autodoc2 JSON database to Myst-MD AST translator. But I should be able to use your Sphinx-extension generated Myst-MD as a reference.

I also see references to Myst xref -- are there any documentation pointers on this that I can use to get a better understanding?

Thank you, Angus!

[thewtex]

I also see references to Myst xref -- are there any documentation pointers on this that I can use to get a better understanding?

I found this myst-xref-json description and this Guide entry on External References, which also mentions Intersphinx objects.inv.

[agoose77]

If you really want to drop Sphinx and directly move to autodoc2, then you will want to think about where you pull in the docs.

What I would suggest is generation of .myst.json documents from autodoc.db.json, and then you can pull those in to your build. You can see what a .myst.json file should contain by investigating the .json endpoint of a normal MyST page e.g. https://mystmd.org/guide/frontmatter.json

[thewtex]

Great, thanks for the guidance @agoose77 🙏

Is there a plan to list the Python autodoc node types in the Myst Schema Node Type Index or someplace else?

[agoose77]

@thewtex the new plan is to avoid updating our AST by transforming the Spinx AST into MDAST nodes and adding some annotations (classes).

[thewtex]

@agoose77 cool, thanks for the clarification.