search

executablebooks / MyST-Parser

An extended commonmark compliant parser, with bridges to docutils/sphinx
https://myst-parser.readthedocs.io
MIT License
737 stars 196 forks source link

include tree outside docs source directory #401

Open jedbrown opened 3 years ago

jedbrown commented 3 years ago

Is your feature request related to a problem? Please describe.

We've been keeping general documentation under doc/sphinx/ while keeping example documentation alongside the examples, as in examples/fluids/index.md. These files contain a sort of theory manual as well as information on running and extending the examples.

Common advice prior to MyST has been to have some code in conf.py that copies such files into doc/sphinx/examples/fluids/index.md, but this just feels dirty and also causes "Edit this page" links to 404. I was hoping that the MyST includes feature (https://myst-parser.readthedocs.io/en/latest/sphinx/use.html#include-a-file-from-outside-the-docs-folder-like-readme-md) could be used for this, but it appears not.

Describe the solution you'd like

I would love to be able to include ../../examples/index.md and then use relative paths within the tree, keeping conf.py under a docs/ subdirectory.

Describe alternatives you've considered

  1. Keep coping as we've been doing.
  2. Manually maintain examples documentation in doc/sphinx/examples/.
  3. Promote conf.py to the top level and make needed adjustments to exclude_patterns.

In retrospect, I think 3 would have saved significant time over the years, it's just disappointing to require a non-namespaced file at the top level. If that's the pragmatic solution, feel free to close this.

schmoelder commented 1 year ago

I know this issue is kind of old but did anyone find a good solution for this?

I have the exact same situation that examples live in my project root. Here, I use jupytext to keep myst/.ipynb/.py files in sync. I would love to simply include them in the main toctree..

cclauss commented 1 week ago

I sense that I cannot nest one MyST directive inside another like:

```{toctree} :maxdepth: 2 :caption: Contents

```{include} ../README.md ``` ```

Is there an alternate syntax that would allow importing the parent directory's README.md into the toctree?

Can someone please show me how I can change: https://myst-parser.readthedocs.io/en/latest/syntax/organising_content.html#using-toctree-to-include-other-documents-as-children to include

  1. ../content_child1.md instead of examples/content_child1.md and
  2. ../content_child2.md instead of examples/content_child2.md?

@chrisjsewell