[Yum-devel] [PATCH] Adds initial files for automatically generating html documentation.

[Nick Jacek]

Yeah, I'm making these files 'by hand'.  Sphinx works on sort of a hybrid model where you can add extra info to the documentation, but also pull in other sections automatically from the source code.  These files look the way they do because the only thing they do is tell sphinx to pull in info automatically without anything else.  I have written a little script that does most of the work of creating these files, then I just sometimes need to tweak them a little bit; as far as I can tell there's no way to get sphinx to do this for me.  Though come to think of it, there may be a way to integrate my script into the sphinx config files.

---
Nick Jacek

----- Original Message -----
From: "James Antill" <james at fedoraproject.org>
To: "yum development" <yum-devel at lists.baseurl.org>
Sent: Wednesday, 20 July, 2011 12:13:21 PM
Subject: Re: [Yum-devel] [PATCH] Adds initial files for automatically generating html documentation.

On Wed, 2011-07-20 at 11:08 -0400, Nick Jacek wrote:
> These files tell sphinx where to look in the source code to generate
> the documentation.  In the future, they could also be edited to add
> documentation about the modules that we want online, but not in the
> source code, such as long usage examples.  These files don't have to
> go in the git repo, but then I'm not sure where else to put them.
> Also, since sphinx can't generate the documentation without these
> files, if we don't put them in the git repo, I'm not sure it makes
> sense to put any of the sphinx config files at all in the repo.

 Ok, so they aren't automatically generated?

 Eg. the cli.rst file:

index 0000000..8679906
--- /dev/null
+++ b/docs/sphinxdocs/cli.rst
@@ -0,0 +1,27 @@
+cli
+===
+.. automodule:: cli
+
+.. autofunction:: sigquit
+
+CliError
+--------
+.. autoclass:: CliError
+   :members:
+   :show-inheritance:

...looks like it's just a dump of (part of) the documentation comments
in that file. Are you writing the above by hand?

_______________________________________________
Yum-devel mailing list
Yum-devel at lists.baseurl.org
http://lists.baseurl.org/mailman/listinfo/yum-devel