Open
Description
The current docs describle the following folder layout and config:
.
├── doc
│ ├── conf.py
│ ├── index.rst
| ├── make.bat
│ └── Makefile
├── my_python_module
│ ├── __init__.py
│ └── mod.py
└── examples
├── plot_example.py
├── example.py
└── README.txt (or .rst)
sphinx_gallery_conf = {
'examples_dirs': '../examples', # path to your example scripts
'gallery_dirs': 'auto_examples', # path to where to save gallery generated output
}
I find this not ideal for the following reasons.
- the input folder (
examples) is at the top level in the project. I rather see it as part of the documentation, so it should be indocs. - The naming of the input folder
examplesdoes not give any hint that this is input. - The output folder name becomes part of the sphinx document structure and hence URL. While
auto_exampleis descriptive on how this is generated, its irrelevant for the user of the docs.htttps://myproject.org/examples/hello_world.htmlreads much better thanhttps://myproject.org/auto_examples/hello_world.html.
I thus propose to place both folders under docs and name the ouput folder examples and name the input folder examples_inputs, i.e.
.
├── doc
│ ├── examples_inputs
│ │ ├── plot_example.py
│ │ ├── example.py
│ │ └── README.txt (or .rst)
│ ├── conf.py
│ ├── index.rst
| ├── make.bat
│ └── Makefile
├── my_python_module
├── __init__.py
└── mod.py
sphinx_gallery_conf = {
'examples_dirs': 'examples_inputs', # path to your example scripts
'gallery_dirs': 'examples', # path to where to save gallery generated output
}
If you agree with the change, I can make a PR.
Metadata
Assignees
Labels
No labels