How to configure sphinx/sphinx-js to see documents in parent directory. #193
Description
Summary
I cant seem to get sphinx and sphinx_js to see my project code and to generate class and function documentation. It only generates boilerplate.
Details
After a bit of trial and error I got sphinx and sphinx-js installed in the following fashion:
npm install jsdoc -g
conda create -name docs python=3.9
conda activate docs
conda install -c conda-forge/label/cf202003 nodejs
conda install -c conda-forge sphinx
conda install -c conda-forge sphinx-js
I then ran the following in a docs subfolder within my project:
sphinx-quickstart
I then updated conf.py (see below). Once I added the sphinx_js extenion, I ran the following:
make html
The parent of "docs" is a project with a couple of JS files.
The generated documentation was just the boilerplate framework, within no functions or classes actually documented.
I also tried uncommenting the following block when I saw no documentation:
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
The results of the make follows (See description below to see that I eliminated the warning in red):
The parent directory (..) contains the following structure.
Though a web page is generated, I see no classes documented.
My index is empty.
The entire conf.py seen below:
(docs) [dsargrad@sdbie-sargrad docs]$ cat 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
sys.path.insert(0, os.path.abspath('..'))
# -- Project information -----------------------------------------------------
project = 'VAM Event Streamer'
copyright = '2022, SPO'
author = 'SPO'
# -- 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_js'
]
# 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 = ['_build', 'Thumbs.db', '.DS_Store']
# -- 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']
js_source_path = '../'
I also tried running
sphinx-apidoc -o . ..
But this did not help, in fact it was the source of the warning seen above.
Eliminating that call eliminated the modules.rst warning seen in red above.
