xfce4-docs update

[Jim Campbell]

Hi All,

On Tue, Sep 22, 2009 at 9:55 AM, Jannis Pohlmann <jannis at xfce.org> wrote:
> Hey all,
>
> I've started setting up the xfce4-docs repository. It acts as some kind
> of meta-repository that is not supposed to be installed (other than on
> the machine of documentation people). We can include it in the
> repositories of individual components as a git submodule.
>
> In order to build the docs for a certain component, we'll most likely
> have to:
>
>  1. Check for python, sphinx-build and the xfce.sphinx.crossref python
>     module in configure.
>  2. Export an environment variable XFCE4_DOCS_PROJECT containing the
>     name of the component to use, in configure or autogen.sh.
>  3. Add AC_CONFIG_SUDBDIRS([docs]) to each component's
>     configure.{ac,in.in} to enable recursive configure.
>
> It think it would be a good idea to wrap 1. and 2. in an xfce4-dev-tools
> macro called XDT_DOCS(PROJECT_NAME) or XDT_FEATURE_DOCS(PROJECT_NAME).
> Any objections?
>
> I wonder where to put the xfce.sphinx.crossref python module though.
> It's a module I wrote for sphinx/reStructuredText which makes it
> possible to add links between independent component docs. The python
> module takes the installation prefix of the build into account. If
> someone wants to add a link from the thunar docs to the index page of
> thunar-thumbnailers, he could simply do so like this (in reST):
>
>  :xfce:`thunar-thumbnailers:index`
>
> A link to a different page would look like this:
>
>  :xfce:`thunar-media-tags:howto/bulk-rename`
>
> As I said, I'm not sure where to put it. We can either package it on its
> own and upload it to http://pypi.python.org/ and simply make all
> components with docs depend on it, or add it to something all other
> components depend on anyway (which will be hard as xfce4-docs isn't
> necessarily limited to core components). So I'm leaning towards the
> first option. Ideas, opinions?
>
>  - Jannis
>

With regards to the Xfce-specific python module, is it something that
other rST-based projects could use if faced with a similar situation?
Or is it coded in such a way to really only be beneficial to our
particular setup?  If it is the former, is it possible to not include
xfce in the module name and usage?

I noticed that there are a lot of GNOME or KDE-specific python modules
up on the site you linked to, so feel free to disregard this if it
isn't relevant (or if it isn't practical).

I would have to think up a new link syntax . . .  :extlink:, :extlnk:
or :cxdoclink: come to mind.  (The last option would come across as
"cross-doc link.").

Again, feel free to disregard is this isn't relevant or practical.
Thanks!!!  :-)

Jim