There were a number of occurrences where we used nested inline markup
(verbatim + refs) which is currently not possible with RST syntax [1].
There is a possible workaround involving substitution definitions like
.. |virConnectPtr| replace:: ``virConnectPtr``
.. _virConnectPtr: /html/libvirt-libvirt-host.html#virConnectPtr
Substitutions cannot be made generic, hence we cannot create a template
for substitution and use a single template everywhere, so we'd end up
with a lot of clutter and convolution. Therefore, we can make an
exception and just link the data type without further style markup.
[1] https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible
Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Move docs/kbase.rst to docs/kbase/index.rst so that the directory itself
shows our index page rather than the autogenerated list of files by the
webserver.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
When using .path() for an argument to a python script meson will not
setup dependancies on the file. This means that changes to the generator
script will not trigger a rebiuld
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Meson unfortunately doesn't give us any means to share the code using
xsltproc to output HTMLs processed by our template. This means we will
have to resort to copy&paste engineering.
To make things simpler, let's use the same block of code in
docs/meson.build but also any of the subdirs which generate htmls.
This will be achieved by making it configurable and wrapping it in a
comment that instructs anybody editing it to keep it identical.
We need to be able to configure the template file used and installation
directory. The rest of the processing is same as we do in
docs/meson.build.
This code will then be copied to subdirs to refactor the current
approach used there.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
Since we no longer reformat the XSLT-transformed files, there's no need
to use an external script any more.
Unfortunately this hid errors from 'xsltproc' as return value was not
checked and the stderr was piped into xmllints stdin. The result was
that any invalid input file would result into an empty output file.
Since the script's only purpose was to prevent additional temporary
files at the time we were reformatting the output in a pipeline we no
longer need this.
Moving the generation directly into the meson definition makes it more
obvious what's happening and saves readers from having to parse what's
going on. A free bonus is that errors are now properly caught and
reported.
This patch converts the main docs/ directory for now with cleanup of
other comming later.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
Only 'acl.html' output file includes that file so there's no need to
make everything depend on it.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
We switched to meson in the meantime so the conversion
to HTML has to be explicitly requested.
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
For now just plain conversion to rst. Anchors which existed until now
are preserved, but the table of contents now uses the docutils-generated
ones.
Additionally <code> which was nested in a link (<a>) was removed as rst
doesn't support nesting of inline markup.
The only anchor which wasn't restored is
'elementsDiskBackingStoreIndex' and its only reference was removed.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
'docutils' add a stylesheet to the output html file for direct
consumption. Since we use the html files just as an intermediate step
which is post-processed to add our own stylesheet and drop the docutils
one in the process we can ask 'rst2html' to not add any for an
intermediate file with less garbage.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
NEWS.rst is based in the root of the repository and 'hvsupport.html'
doesn't have a backing file which can be edited since it's fully
generated. Our 'contribute -> edit this page' link on the bottom of the
page is wrong in those cases.
Fix it by adding the contribute section only when there's a source and
base the 'source' of a html file in the root of the repository.
Along with that we need to modify the scripts/meson-html-gen.py script
to accept optional 'pagesrc' and the XSL template to skip the
'contribute' section when we don't have a source.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Just convert 'docs_html_in_files' into 'docs_html_in_gen'. The target
definitions for those were almost the same.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
