When compiling NetworkManager with --enable-gtk-doc outside the
source tree, the generated documents are slightly different from
those generated in tree. This patch fixes that missed COPYING file in
$(top_builddir) and adds $(top_builddir)/libnm-util to DOC_SOURCE_DIR.
https://bugzilla.gnome.org/show_bug.cgi?id=742139
Signed-off-by: You-Sheng Yang <vicamo@gmail.com>
Move the settings/plugins doc generation from libnm-util to
libnm-core, since libnm-util isn't being updated for all new
properties.
With this commit, the keyfile and ifcfg-rh documentation is basically
unchanged, except that deprecated properties are now gone, and new
properties have been added, and the sections are in a different order.
(generate-plugin-docs.pl just outputs the settings in Makefile order,
and they were unsorted in libnm-util, but are sorted in libnm-core).
The settings documentation used for nm-settings.5, the D-Bus API docs,
and the nmcli help is changed a bit more at this point, and mostly for
the worse, since the libnm-core setting properties don't match up with
the D-Bus API as well as the libnm-util ones do. To be fixed...
(I also removed the "plugins docs" line in each plugin docs comment
block while moving them, since those blocks will be used for more than
just plugins soon, and it's sort of obvious anyway.)
docs/api/settings-spec.xml was accidentally not getting disted,
because gtk-doc.make explicitly removes all DISTCLEANFILES from
distdir. However, it doesn't actually make sense for the settings docs
files to be in DISTCLEANFILES anyway; they were put there rather than
CLEANFILES (IIRC) so that "make clean" in a tarball build wouldn't
delete them and break things. But the right fix is to just make them
only be in CLEANFILES when BUILD_SETTING_DOCS is true, and not ever
get deleted otherwise.
Also adjust the build rules to ensure that the generated docs don't
get rebuilt in tarball builds, since that can cause problems when
building from a read-only source tree, etc.
Meanwhile, in an unrelated but also fatal bug, configure.ac's check
for if the generated docs were already present never got updated for
the cli/src -> clients/cli move, and so even if we had been disting
settings-spec.xml, configure would still think that the tarball didn't
have all of the generated docs in it, so SETTING_DOCS_AVAILABLE would
be set false and none of the generated docs would get used.
https://bugzilla.gnome.org/show_bug.cgi?id=740035
Certain build configurations (like --enable-gtk-doc
--disable-introspection) were broken with respect to nm-setting-docs.
Fix this. Also, we don't require just gobject-introspection, we need
pygobject specifically as well.
dist tarballs shouldn't ever be released without the documentation,
and this allows us to build the tarballs with pre-generated docs
that get installed on the end system, but don't need to be built
there. So the end system doesn't need gtk-doc installed, only
the dist system does.
https://bugzilla.gnome.org/show_bug.cgi?id=700093
"./autogen.sh --enable-doc && make" produced this error:
warning: failed to load external entity "../settings-spec.xml"
../network-manager-docs.xml:57: element include: XInclude error : could not load ../settings-spec.xml, and no fallback was found
Removing settings-spec.xml from $(content_files) made the file non-DISTed but it
also removed the file as a dependency for html-build.stamp that also runs
cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
and $(DOC_MAIN_SGML_FILE) includes settings-spec.xml.
Fix that by making $(DOC_MAIN_SGML_FILE) dependent on setting-spec.xml.
The generated settings-spec.xml should not be DIST-ed because it's
regenerated every time libnm-util changes. That meants it gets
rebuilt during 'make' even from a dist tarball. Thus, it shouldn't
be part of the dist tarball itself.
In addition, settings-spec.html shouldn't be included in
$(content_files) becuase this is added to EXTRA_DIST by gtk-doc.make.
Since generate-settings-spec.c the move from docs/api/ to tools/,
this started breaking distcheck even though the original Makefile
rules were wrong too.
The refentry xml is used to generate manual page with settings description.
The invocation is:
generate-settings-spec <type> <output file> [<type> <output file>]
where <type> is "book" or "refentry"
Use --enable-doc and --enable-tests instead of --with-docs and
--with-tests. This is consistent with other features and with
--enable-gtk-doc option. Support current variants as fallback.
Don't build tests unless --enable-tests is specified.
Since all.xml is a built file these days, and will contain paths
relative to $(top_srcdir)/introspection even though it's not in
that directory, it seems we need to clue xsltproc into where the
other API XML files really are.
Apparently sometimes when doing the distcheck the generator can't
open the file for writing (gets ENOACCESS) presumably because there's
already a file there that's read-only. So remove any existing
settings spec before regenerating.
gtk-doc removes the 'html' directory as part of the build process
so we need to have spec.html generation depend on the gtk-doc html
target. Also, fix up the paths to make sure the generated spec.html
gets copied into the final 'html' directory.
