doc: decode the objects.inv file #12701
Conversation
|
@gabrielmougard The doc build for the snap uses the general |
|
|
||
| .PHONY: doc-incremental | ||
| doc-incremental: | ||
| @echo "Build the documentation" | ||
| . $(SPHINXENV) ; LOCAL_SPHINX_BUILD=True sphinx-build -c doc/ -b dirhtml doc/ doc/html/ -d doc/.sphinx/.doctrees -w doc/.sphinx/warnings.txt | ||
|
|
||
| .PHONY: doc-objects | ||
| doc-objects: | ||
| . $(SPHINXENV); cd doc/html; python3 -m sphinx.ext.intersphinx 'objects.inv' > objects.inv.txt |
There was a problem hiding this comment.
I assume the resulting objects.inv.txt will be shipped along the docs -- just like the objects.inv file. Is that correct?
There was a problem hiding this comment.
That's the plan - but I just noticed that this will only work for the local docs, not the online version (because RTD doesn't use the Makefile). Let me add it for RTD as well ...
There was a problem hiding this comment.
ru-fu
force-pushed
the
decode-objects-inv
branch
from
1362a54
to
e99c9ec
Compare
ru-fu
force-pushed
the
decode-objects-inv
branch
2 times, most recently
from
05cddfa
to
eeaa08c
Compare
yes. Here is the snap doc build step that ships the built doc: if [ "$(uname -m)" != "riscv64" ]; then
# Build the static website
make doc
# Copy the static website
mkdir -p "${CRAFT_STAGE}/share/lxd-documentation"
cp -a doc/html/. "${CRAFT_STAGE}/share/lxd-documentation/"
fi |
Currently 170 KiB. |
|
|
||
| .PHONY: doc-incremental | ||
| doc-incremental: | ||
| @echo "Build the documentation" | ||
| . $(SPHINXENV) ; LOCAL_SPHINX_BUILD=True sphinx-build -c doc/ -b dirhtml doc/ doc/html/ -d doc/.sphinx/.doctrees -w doc/.sphinx/warnings.txt | ||
|
|
||
| .PHONY: doc-objects | ||
| doc-objects: | ||
| . $(SPHINXENV); cd doc/html; python3 -m sphinx.ext.intersphinx 'objects.inv' > objects.inv.txt |
There was a problem hiding this comment.
What format is this new file in @ru-fu ?
Also, is it possible to add a comment here explaining what its intended to be used for? I.e to be consumed by the UI?
There was a problem hiding this comment.
It's a text file.
And do you mean a comment in the Makefile? I have an explanation in this PR.
There was a problem hiding this comment.
Yeah in the makefile thanks.
Are the UI team able to parse the text file?
There was a problem hiding this comment.
@edlerd suggested this change, so I would assume so. ;)
There was a problem hiding this comment.
Are the UI team able to parse the text file?
We have to write a parser for it, but that should be trivial. So: Yes.
There was a problem hiding this comment.
@edlerd you've seen the text format and happy with it?
ru-fu
force-pushed
the
decode-objects-inv
branch
from
eeaa08c
to
2bd71f3
Compare
Sphinx creates an objects.inv file that contains a mapping of IDs and locations in the docs. The UI needs this mapping to be able to resolve links within the descriptions of config options. The UI would require additional dependencies to decode the objects.inv file, so providing the decoded version with the documentation is easier. Signed-off-by: Ruth Fuchss <ruth.fuchss@canonical.com>
ru-fu
force-pushed
the
decode-objects-inv
branch
from
2bd71f3
to
34b67b7
Compare
|
LGTM! |
Sphinx creates an objects.inv file that contains a mapping of IDs and locations in the docs. The UI needs this mapping to be able to resolve links within the descriptions of config options.
The UI would require additional dependencies to decode the objects.inv file, so providing the decoded version with the documentation is easier.