Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs build borked #44

Closed
lkubb opened this issue Nov 15, 2023 · 0 comments · Fixed by #45
Closed

docs build borked #44

lkubb opened this issue Nov 15, 2023 · 0 comments · Fixed by #45

Comments

@lkubb
Copy link
Contributor

lkubb commented Nov 15, 2023

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:

  1. .pre-commit-hooks/make-autodocs.py by accident strips the module names from the doc file names
  2. autosummary is instructed in docs/conf.py to generate its own stubs via autosummary_generate = True, which conflict with the other ones
  3. 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant