Placing all sphinx files in separate directory

Question

I want to keep all my sphinx files in their own directory documentation/, so that my project looks like this:

.
├─ documentation
│  ├─ _static/
│  ├─ _templates/
│  ├─ build/
│  ├─ index.rst
│  ├─ Makefile
│  ╰─ conf.py
╰─ source
   ╰─ main.py

In documentation/Makefile I have set the source directory:

SOURCEDIR = ../source

In documentation/conf.py I've added the source path:

import os
import sys


sys.path.insert(0, os.path.abspath('../source'))

I haven't changed the default values in index.rst.

My output when I build:

$ cd documentation
$ sphinx-build . build/

Running Sphinx v4.1.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

The HTML pages are in build.

It generates documentation/build/index.html as you would expect, but it hasn't actually done the auto-documentation. There's nothing there:

My guesses are:

I need to specify which files to document in index.rst
I haven't pointed Sphinx to my source directory correctly

Try adding `.. automodule:: main` in index.rst and `extensions = ["sphinx.ext.autodoc"]` in conf.py. See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html. — mzjn, Apr 22 '22 at 14:34
`SOURCEDIR = ../source` looks strange. `SOURCEDIR` refers to the directory where the .rst files are. — mzjn, Apr 22 '22 at 15:06
Put an `__init__.py` in `source` to make it a Python package. Also please show the `.rst` file that contains [autodoc directives](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc). — Steve Piercy, Apr 23 '22 at 07:25
See [this answer](https://stackoverflow.com/a/59951675) for a solved example of your layout. — bad_coder, Apr 29 '22 at 16:14

Placing all sphinx files in separate directory

0 Answers0