Give a special mention to toctree directive in docs

[hukkin]

I feel like the docs could maybe give a special mention to the toctree directive, given how its usage seems mandatory for anything but the most trivial single page docs.

Not sure what the right place would be, perhaps somewhere here?: https://myst-parser.readthedocs.io/en/latest/using/howto.html

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[choldgraf]

Totally agreed - I was actually thinking about re-orging the documentation a bit in order to follow this documentation framework: https://documentation.divio.com/

(basically: tutorials, how-tos, reference, and explanation)

I think that the toctree explanation would be an important part of a "getting started with MyST" tutorial.

[hukkin]

Actually I think the problem could be generalized beyond toctree a bit.

The docs are obviously written by the developers, and reading as a user, I think it shows a bit.

As a user I don't necessarily care about a generalized syntax description, or the fact that all directives can be parameterized via

```{directivename} arguments
```

As a user the syntax

```{toctree}
```

is no less of a syntax to me compared to something like the bold syntax __this is bold__. At the end of the day I just want to see a toctree or bold text on screen, and need to know how to write that in MyST.

Maybe MyST should either:

• duplicate a significant portion of Sphinx docs but write them with MyST in mind, not reST. I guess this page for example is important https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html (note how there is restructuredtext in the URI resource but AFAICT this is the only good resource for MyST user currently...)
• add MyST examples directly to Sphinx docs so that every syntax is shown there in both reST and MyST

[chrisjsewell]

Cheers for the feedback, here and in hukkin/mdformat#149 (comment)

duplicate a significant portion of Sphinx docs but write them with MyST in mind

This is already discussed in #267 and #81, and the idea is to do auto-conversion with https://github.com/executablebooks/rst-to-myst

The docs are obviously written by the developers, and reading as a user, I think it shows a bit.
As a user I don't necessarily care about a generalized syntax description, or the fact that all directives can be parameterized via.

Well yes and no.
It depends on whom the target user is: if they are already using sphinx+RST and looking to switch to Markdown, then it is helpful to understand that the MyST role/directive syntax is directly translatable from RST, then you should already know about toctree etc. This is probably the main focus of the myst-parser documentation

If you are coming from a position of no knowledge of sphinx etc and want to write new documentation, as I know you are, then yes maybe you don't want this.
But then really I would say this is pretty much what the https://jupyterbook.org documentation targets (but with a few critical differences with the use of _config.yml and _toc.yml).

So the questions I've raised before is what is the balance between these documentations: do we want this essentially duplication in documents (but from different perspectives) or should they be merged into a single site
(note there is also the myst-nb documentation)

This also extends to your other points:

As a total noob, comparing Sphinx+MyST with MkDocs, what seems tempting about MkDocs to me is:

Configuration is YAML, not Python source code. This feels "right" if my use case is simple and I couldn't care less about programming Sphinx. This probably makes it also a lot more approachable to non-Python projects.

This is how jupyter-book works and, as discussed in executablebooks/meta#285 (reply in thread), perhaps there is a way to make this work with "vanilla sphinx" (and the way jupyter-book builds the ToC via the top-down _toc.yml

its built from the ground up with Markdown in mind. Sphinx docs focus on reST.

Again jupyter-book focusses principally on Markdown

The material theme (used by FastAPI among others) is great. Has dark mode. Has the dual pane navigation. There's a Sphinx port but that lacks dark mode for instance.

This is something we are essentially already working on in with others (including the developers of PyPI and Pandas) in executablebooks/meta#279 😄

a nice built-in docs server for development

This is perhaps similar to another piece of work in the pipeline: executablebooks/meta#192

[vsoch]

heyo! I came here looking for how to define a toctree in markdown using MyST. I tried the suggested {toctree} but it didn't seem to work? Can anyone point me to a working example? Thank you!

[agoose77]

@vsoch have you checked for any warnings in the console window e.g. about indentation? You should not intend the entries.

[vsoch]

ah! Let me try a quick render again.

[vsoch]

Ahhh that totally worked!!! Here is what it looks like in the markdown (click edit to see the toctree) or see screenshot below

:maxdepth: 1
Getting Started <https://oras.land/client_libraries/1_python/>
getting_started/index.md
contributing.md
about/license

:caption: API
:maxdepth: 1
source/modules.rst

Thank youuuu!

[agoose77]

Fab, I ran into this today as well!

[chrisjsewell]

Note, that I added this section to the docs not long ago: https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#toc-trees
It just contains some auto-generated stuff at the moment, but feel free to drop a PR adding some more text 😄

[72757373656c6c]

Like vsoch, I found this link while searching for details on toctree and how to organize a project. The structure of a multiple file project and configuring the files that contain toctree(s), coupled with a theme's restrictions and features, seems to be the foundation of an easy to use and maintain project.

During this process, I was also looking for a way to comment files/lines inside a toctree to quickly remove, add or document within a toctree.

I did find that a % could be used. However, it produces a warning that indicates the file doesn't exist. Sphinx-MyST seems to be looking for a file prefixed with a % rather than treating the whole line as a comment.

An up-to-date working Sphinx+MyST demo would be helpful with multiple directories, includes, and images. It would show the file layout on disk, conf.py, index.md files, and the user could compile and manipulate it to learn. Use that same example, within the MyST documentation, so a user could read the doc and then try it on their system. Live examples are nice, but I want to be able to replicate the process on a local system, so if a particular configuration, extension, or other is required, that needs to be shown some place. I know the MyST documentation has download the .md file for the current page, which is very nice, but it cannot be compiled.

Some other questions after reading "Organising content":

1. Why would a user want to set the title in the front-matter vs just using the markdown titles (#)?
2. What are sub-toctrees and what are they good for?
3. What is the difference between include and literalinclude, other than "longer pieces of code".

Is there a particular forum where questions could be asked?

Thank you.

environment:
archlinux, xfce
python-sphinx 7.2.6-1
python-myst-parser 2.0.0-1
python-sphinx-furo 2023.09.10-2
python-sphinx-copybutton 0.5.2-1