build: update docs build #2339
build: update docs build #2339
Conversation
.kokoro/publish-docs.sh
Outdated
| --github-repository=$(jq --raw-output '.repo // empty' .repo-metadata.json) \ | ||
| --issue-tracker=$(jq --raw-output '.issue_tracker // empty' .repo-metadata.json) | ||
|
|
||
| cat docs.metadata |
There was a problem hiding this comment.
This will be fixed in cl/742192972
.kokoro/publish-docs.sh
Outdated
| # create metadata | ||
| python3 -m docuploader create-metadata \ | ||
| python3.10 -m docuploader create-metadata \ |
There was a problem hiding this comment.
Where is docuploader being installed now? I see it uses to be pip installed in this file.
There was a problem hiding this comment.
This script was moved internally and is no longer included in this PR.
noxfile.py
Outdated
| @@ -644,7 +644,9 @@ def snippetgen(session): | |||
|
|
|||
| @nox.session(python="3.10") | |||
| def docs(session): | |||
| """Build the docs.""" | |||
| """Build the docs for this library.""" | |||
There was a problem hiding this comment.
This is just for the generator, right? We could reword to minimize confusion.
| """Build the docs for this library.""" | |
| """Build the docs for this generator.""" |
parthea
force-pushed
the
update-docs-build
branch
from
e011566 to
9837f1d
Compare
| "-b", | ||
| "html", | ||
| "-d", | ||
| os.path.join("docs", "_build", "doctrees", ""), | ||
| os.path.join("docs", ""), | ||
| os.path.join("docs", "_build", "html", ""), |
There was a problem hiding this comment.
Thanks for documenting the args above! I suggest document the following, and also putting arg values on the same line as their args:
| "-b", | |
| "html", | |
| "-d", | |
| os.path.join("docs", "_build", "doctrees", ""), | |
| os.path.join("docs", ""), | |
| os.path.join("docs", "_build", "html", ""), | |
| "-b", "html", # builder | |
| "-d", os.path.join("docs", "_build", "doctrees", ""), # cache directory | |
| # paths to build: | |
| os.path.join("docs", ""), | |
| os.path.join("docs", "_build", "html", ""), |
I'm basing this interpretation of the args on https://www.sphinx-doc.org/en/master/man/sphinx-build.html
| "sphinx-build", | ||
| "-T", # show full traceback on exception | ||
| "-N", # no colors | ||
| "-D", |
There was a problem hiding this comment.
As in the previous comment, explain more of the args
| @@ -86,7 +86,7 @@ | |||
| # The theme to use for HTML and HTML Help pages. See the documentation for | |||
| # a list of builtin themes. | |||
| # | |||
| html_theme = "sphinx_rtd_theme" | |||
| html_theme = "alabaster" | |||
There was a problem hiding this comment.
Just curious on why the theme change? I think I do prefer "alabaster" to "rtd", but I think the paramount issue is being consistent throughout.
Towards #2338