Open Stack

On 06/09/2015 06:11 PM, Karen Bradshaw wrote:
> Hi.  I am having a build issue with an included file in common-rst.
> I have a file with a toc in admin-guide-cloud-rst/source
> and the included file in common-rst or the local linked dir of common.
> The RST parser complains about
> openstack_manuals/doc/user-guide/source/common/<myfile>. Of course this
> common dir links to common-rst where the file resides.  Problem sharing
> the contents of the common dir with user guide and admin cloud guide?  I
> can move the file, objectstorage_characteristics, out of the common dir.

What happens is that we link common-rst to each RST guide and RST hates 
orphaned files. So, when you add a file to common-rst and include it 
only from the admin-guide-cloud-rst directory, the build of user-guide, 
user-guide-admin, and networking-guide will fail since the file is not 
part of any TOC.

So, there are several options:

1) There are lots of files in common that are used only in one guide - 
so it's time to clean them up. If you have a file that is really only 
used in the admin-guide-cloud, don't put it into common-rst, put it into 
admin-guide-cloud-rst.

2) You can mark a file as ":orphan:". This way it will still get build 
but Sphinx will not error out if it's not included in a TOC.

3) Blacklist a file, using the doc/.../source/conf.py variable 
exclude_patterns. Just add the filename to all RST guides.

If anybody has a better way, please propose and implement ;)

Andreas
-- 
  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
    GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
        HRB 21284 (AG Nürnberg)
     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126