MyST-Parser icon indicating copy to clipboard operation
MyST-Parser copied to clipboard

include tree outside docs source directory

Open jedbrown opened this issue 3 years ago • 2 comments

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.

jedbrown avatar Jun 25 '21 20:06 jedbrown

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..

schmoelder avatar Mar 02 '23 11:03 schmoelder