Doc system and tool help overhaul #2247
Conversation
even when it has a command and that command is not equal to the plugin name
docs/build.sh
Outdated
| fi | ||
|
|
||
| "$sphinx" -a -b html . ./docs/html -w ./docs/_sphinx-warnings.txt -j "$JOBS" "$@" | ||
| "${SPHINX:-sphinx-build}" -E -b html -d build/docs/html . docs/html -w build/docs/html/_sphinx-warnings.txt -j "${JOBS:-auto}" "$@" |
There was a problem hiding this comment.
I would like to leave -E out if possible because it makes incremental builds much slower. Could you give some more details on the issue in fdd406b?
There was a problem hiding this comment.
As per our discussion on discord, removing -E is fine here. Without -E, behavior is inconsistent, but that's fine for a dev script like this.
CMakeLists.txt
Outdated
| add_custom_command(OUTPUT ${SPHINX_OUTPUT} | ||
| COMMAND ${SPHINX_EXECUTABLE} | ||
| -a -E -q -b html | ||
| -E -q -b html -d "${CMAKE_BINARY_DIR}/docs/html" |
There was a problem hiding this comment.
What was the reasoning for removing -a? f1cb9b9 doesn't really explain it. My recollection is that -a was added to force output to be written to disk so that CMake recognizes when the target has been built and won't try to rebuild it on every build.
There was a problem hiding this comment.
The comment in CMakelists indicates that it is only docs/html/.buildinfo that CMake cares about, and we touch that file explicitly to communicate success to CMake. We don't need to touch all files.
Notable changes: - can build any combination of output formats in series - `-E` is no longer passed by default to aid in development, but can be passed manually
|
pre-commit.ci autofix |
for more information, see https://pre-commit.ci
myk002
changed the title
also fix tag syncing command so short descriptions with internal periods are parsed correctly
Under Sphinx 5, `topic` nodes now render as `<aside>` elements, and without an explicit background color
Previously rendered as e.g. "CtrlShiftK"
now that labels are no longer bolded in the text rendering, the header detection code needs updating
and to have a forum for code feedback (though I plan to merge this branch into develop piece by piece in separate PRs)