title: How to correctly set up a project directory for Sphinx
body: <p>I've looked at numerous tutorials and videos taking one through the process of generating documentation using Sphinx, and at this point I am convinced that there is something wrong with my project structure. I am running Windows 10 Pro, 2004; Python 3.7.9; Sphinx 3.3.0.</p>
  <p>I created a completely fresh project <code>sphinx_test</code> to test my Sphinx skills by following these steps:</p>
  <ol>
  <li>Create a new virtualenv <code>python -m virtualenv sphinxtest</code></li>
  <li>Activate it <code>sphinxtest\Scripts\activate</code></li>
  <li>Install Sphinx and requirements <code>pip install sphinx</code></li>
  <li>Create a new project folder <code>mkdir sphinx_test</code> and navigate into it <code>cd sphinx_test</code></li>
  <li>Create subdirectory for source code and all sub-modules to come <code>mkdir src</code></li>
  <li>Create some silly sample <code>*.py</code> files with random docstrings (<code>nopes.py</code> and <code>sqrer.py</code>)</li>
  <li>Create the docs directory <code>mkdir docs</code> <strong>and</strong> navigate into it <code>cd docs</code></li>
  <li>Execute <code>sphinx-quickstart --ext-autodoc</code>, choosing separate <code>build</code> and <code>source</code> directories</li>
  <li>Modify <code>conf.py</code>, adding  <code>./src/</code> to the <code>PATH</code></li>
  <li>Modify <code>index.rst</code>, adding <code>modules</code> beneath <code>toctree</code> group:</li>
  </ol>
  <p><a href="https://i.stack.imgur.com/SQvDY.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/SQvDY.png" alt="modules beneath toctree" /></a></p>
  <ol start="11">
  <li>Run <code>sphinx-apidoc -o .\source\ ..\src\</code> from inside the <code>docs</code> directory.</li>
  <li>Run <code>make html</code> and get the following:</li>
  </ol>
  <pre><code>Running Sphinx v3.3.0
      loading pickled environment... done
      building [mo]: targets for 0 po files that are out of date
      building [html]: targets for 2 source files that are out of date
      updating environment: 0 added, 2 changed, 0 removed
      reading sources... [100%] src
      WARNING: autodoc: failed to import module 'nopes' from module 'src'; the following exception was raised:
      No module named 'src'
      WARNING: autodoc: failed to import module 'sqrer' from module 'src'; the following exception was raised:
      No module named 'src'
      WARNING: autodoc: failed to import module 'src'; the following exception was raised:
      No module named 'src'
      looking for now-outdated files... none found
      pickling environment... done
      checking consistency... done
      preparing documents... done
      writing output... [100%] src
      generating indices... genindex done
      writing additional pages... search done
      copying static files... done
      copying extra files... done
      dumping search index in English (code: en)... done
      dumping object inventory... done
      build succeeded, 3 warnings.
      
      The HTML pages are in build\html.
  </code></pre>
  <p>This is the folder structure at present:</p>
  <pre><code>C:.
  ├───docs
  │   │   make.bat
  │   │   Makefile
  │   │
  │   ├───build
  │   │   ├───doctrees
  │   │   │       environment.pickle
  │   │   │       index.doctree
  │   │   │       modules.doctree
  │   │   │       src.doctree
  │   │   │
  │   │   └───html
  │   │       │   .buildinfo
  │   │       │   genindex.html
  │   │       │   index.html
  │   │       │   modules.html
  │   │       │   objects.inv
  │   │       │   search.html
  │   │       │   searchindex.js
  │   │       │   src.html
  │   │       │
  │   │       ├───_sources
  │   │       │       index.rst.txt
  │   │       │       modules.rst.txt
  │   │       │       src.rst.txt
  │   │       │
  │   │       └───_static
  │   │               alabaster.css
  │   │               basic.css
  │   │               custom.css
  │   │               doctools.js
  │   │               documentation_options.js
  │   │               file.png
  │   │               jquery-3.5.1.js
  │   │               jquery.js
  │   │               language_data.js
  │   │               minus.png
  │   │               plus.png
  │   │               pygments.css
  │   │               searchtools.js
  │   │               underscore-1.3.1.js
  │   │               underscore.js
  │   │
  │   └───source
  │       │   conf.py
  │       │   index.rst
  │       │   modules.rst
  │       │   src.rst
  │       │
  │       ├───_static
  │       └───_templates
  └───src
          nopes.py
          sqrer.py
          __init__.py
  </code></pre>
  <p>And here is my <code>conf.py</code>:</p>
  <pre><code># Configuration file for the Sphinx documentation builder.
  #
  # This file only contains a selection of the most common options. For a full
  # list see the documentation:
  # https://www.sphinx-doc.org/en/master/usage/configuration.html
  
  # -- Path setup --------------------------------------------------------------
  
  # If extensions (or modules to document with autodoc) are in another directory,
  # add these directories to sys.path here. If the directory is relative to the
  # documentation root, use os.path.abspath to make it absolute, like shown here.
  
  import os
  import sys
  import pathlib
  
  path = pathlib.Path(__file__).resolve() / '..' / '..' / '..' / 'src'
  
  # sys.path.insert(0, os.path.abspath('..\src'))
  sys.path.insert(0, os.path.abspath(path))
  
  
  # -- Project information -----------------------------------------------------
  
  project = 'TEST PROJECT'
  copyright = '2020, Cerberton'
  author = 'Cerberton'
  
  
  # -- General configuration ---------------------------------------------------
  
  # Add any Sphinx extension module names here, as strings. They can be
  # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
  # ones.
  extensions = [
      'sphinx.ext.autodoc',
  ]
  
  # Add any paths that contain templates here, relative to this directory.
  templates_path = ['_templates']
  
  # List of patterns, relative to source directory, that match files and
  # directories to ignore when looking for source files.
  # This pattern also affects html_static_path and html_extra_path.
  exclude_patterns = []
  
  
  # -- Options for HTML output -------------------------------------------------
  
  # The theme to use for HTML and HTML Help pages.  See the documentation for
  # a list of builtin themes.
  #
  html_theme = 'alabaster'
  
  # Add any paths that contain custom static files (such as style sheets) here,
  # relative to this directory. They are copied after the builtin static files,
  # so a file named &quot;default.css&quot; will overwrite the builtin &quot;default.css&quot;.
  html_static_path = ['_static']
  
  
  # -- Extension configuration -------------------------------------------------
  </code></pre>