You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Generally, there are two hard dependencies missing from docs.in: furo and sphinx-copybutton.
Then, there are two separate, conflicting docs build jobs:
docs, which is intended to work the same way the Salt docs do, but fails because:
.pre-commit-hooks/make-autodocs.py by accident strips the module names from the doc file names
autosummary is instructed in docs/conf.py to generate its own stubs via autosummary_generate = True, which conflict with the other ones
docs/all.rst is written with the second method in mind
This is the one that will be executed by the workflows currently.
Another issue is that the hook script does not account for no_saltext_namespace (thus rendering module names as src.mypackage.modules.foo_mod) and exits with 0, even if it created/changed files (pre-commit thus does not fail).
Then, docs-html seems to have been introduced because the first did not work. I think it is intended to be used like nox -e 'docs-html(include_api_docs=True,clean=True)', for example. This fails because all.rst references a file that is never being generated: states.rst (it was probably meant as saltext.foo.states.rst, modules.rst exists because it represents all the modules in the package). Removing this reference results in a - imho - needlessly complicated and very nested output. I might be missing something though.
Additionally, the all.rst index is not parametrized with the loader modules that were selected.
The text was updated successfully, but these errors were encountered:
Generally, there are two hard dependencies missing from
docs.in
:furo
andsphinx-copybutton
.Then, there are two separate, conflicting docs build jobs:
docs
, which is intended to work the same way the Salt docs do, but fails because:.pre-commit-hooks/make-autodocs.py
by accident strips the module names from the doc file namesautosummary
is instructed indocs/conf.py
to generate its own stubs viaautosummary_generate = True
, which conflict with the other onesdocs/all.rst
is written with the second method in mindThis is the one that will be executed by the workflows currently.
Another issue is that the hook script does not account for
no_saltext_namespace
(thus rendering module names assrc.mypackage.modules.foo_mod
) and exits with 0, even if it created/changed files (pre-commit thus does not fail).Then,
docs-html
seems to have been introduced because the first did not work. I think it is intended to be used likenox -e 'docs-html(include_api_docs=True,clean=True)'
, for example. This fails becauseall.rst
references a file that is never being generated:states.rst
(it was probably meant assaltext.foo.states.rst
,modules.rst
exists because it represents all the modules in the package). Removing this reference results in a - imho - needlessly complicated and very nested output. I might be missing something though.Additionally, the
all.rst
index is not parametrized with the loader modules that were selected.The text was updated successfully, but these errors were encountered: