1

I'm trying to use the basics of Sphinx to document a small project. But I can't get him to find the files that are in a directory above.

The project structure is as follows:

/Users/machine/workspace/project1

├── BDRespostas.py
├── constantes.py
├── docs
│   ├── conf.py
│   ├── index.rst
│   └── make.bat
├── estatisticas.py
├── migrate_postgre_sqlite.py
├── preProcessamentoTextual.py
└──

And I have tried to configure index.rst in several ways, without success:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   :ref:'estatisticas.py'
   ../BDRespostas.py
   '/Users/machine/workspace/project1/constantes.py'

I also combined several attempts with adding sys.path.insert () to the project directory. If you already managed to make this reference and can help me, I really appreciate it.

mzjn
  • 48,958
  • 13
  • 128
  • 248
erfelipe
  • 460
  • 4
  • 14
  • 1
    `toctree` entries are names of RST files. You cannot use `toctree` to link to Python modules. See https://stackoverflow.com/q/45195363/407651. – mzjn Aug 16 '20 at 18:51
  • Thanks for listening @mzjn , I read your reply. I understood that I can't put the .py in this way then. I went to the documentation and I can't find how to do that, put the .py files that I want to document. I'll continue searching. – erfelipe Aug 16 '20 at 19:03
  • 1
    @erfelipe you are using the project layout without `src` directory, [here is one example](https://stackoverflow.com/a/59951675). Think of the `.rst` files as something intermediate: `.py` -> `.rst` -> `.html`. You create the `.rst` files using `sphinx-apidoc` (look at the example), or you can create the `.rst` files by hand. It are the `.rst` files that will be used by Sphinx to extract the docstrings from the `.py` modules. – bad_coder Aug 16 '20 at 20:23
  • If your simply looking to include files that are located outside your docs directory you can use restructuredtext’s normal include directive[1] which supports relative paths. [1]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment – whme Aug 21 '20 at 07:38

1 Answers1

0

As said above, toctree is for including documents (.rst files), not Python sources. Tell us what do you want to achieve.

To don't gloss over it - toctree can include documents only from the current folder or child folders. I.e. you can't

.. toctree::
   
   ../one.rst
   ../two/three.rst
Matt Warrick
  • 1,385
  • 1
  • 13
  • 22