1. Anuncie Aqui ! Entre em contato fdantas@4each.com.br

[Python] How to correctly set up a project directory for Sphinx

Discussão em 'Python' iniciado por Stack, Setembro 13, 2024.

  1. Stack

    Stack Membro Participativo

    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.

    I created a completely fresh project sphinx_test to test my Sphinx skills by following these steps:

    1. Create a new virtualenv python -m virtualenv sphinxtest
    2. Activate it sphinxtest\Scripts\activate
    3. Install Sphinx and requirements pip install sphinx
    4. Create a new project folder mkdir sphinx_test and navigate into it cd sphinx_test
    5. Create subdirectory for source code and all sub-modules to come mkdir src
    6. Create some silly sample *.py files with random docstrings (nopes.py and sqrer.py)
    7. Create the docs directory mkdir docs and navigate into it cd docs
    8. Execute sphinx-quickstart --ext-autodoc, choosing separate build and source directories
    9. Modify conf.py, adding ./src/ to the PATH
    10. Modify index.rst, adding modules beneath toctree group:

    [​IMG]

    1. Run sphinx-apidoc -o .\source\ ..\src\ from inside the docs directory.
    2. Run make html and get the following:

    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.
    
    
    This is the folder structure at present:
    
    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
    
    
    And here is my conf.py:
    
    # 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 "default.css" will overwrite the builtin "default.css".
    html_static_path = ['_static']
    
    
    # -- Extension configuration -------------------------------------------------
    
    [url="https://stackoverflow.com/questions/64687973/how-to-correctly-set-up-a-project-directory-for-sphinx"]Continue reading...[/url]

Compartilhe esta Página