Creating multiple PDFs that share chapters

[Lenz Grimmer]

Hi,

I've started using Sphinx by converting an existing OpenOffice Document into rst/sphinx (using od2sphinx). I now have a directory "FirstDocument", that contains all the relevant files, e.g. the Makefile, conf.py and the *.rst files that resemble this document.

Now I'd like to create another document, let's call it "SecondDocument". I would like to be able to render both documents as individual PDFs. However, SecondDocument will contain a number of chapters that are part of the "FirstDocument" folder already.
To avoid having to maintain the same files in two locations, I was thinking of creating a directory "common" on the same level as the directories for FirstDocument and SecondDocument and change the index.rst files in both directories to include these files by adding them as "../common/Filename.rst" in the toctrees. However, this does not seem to work, I get the following warning when running "make latexpdf" in the document directories: "WARNING: toctree contains reference to nonexisting document u'common/Filename' - the resulting PDF does not contain the chapters in question.

Do I need to change some option or is there a better approach for creating multiple PDF documents that share some chapters? Any suggestions are welcome.

Thanks!

Lenz

[juh]

Hi Lenz,

I am not sure whether toctree only allows to include files in the same
directory or below – have you tried include instead?

Anyway, you could try another approach.

You can have multiple conf.py files in your project and you can call
sphinxbuild with the option -c to use one of the files, eg:

sphinx-build -c firstdocument.py -b latexpdf sourcedir builddir

and

sphinx-build -c seconddocument.py -b latexpdf sourcedir builddir

Then you have to specify different start files in the configuration
files and different files to be excluded from the build.

That way you have all your files in one directory and build your output
files according to the definitions in the two conf.py-files.

HTH
juh

> --
> You received this message because you are subscribed to the Google
> Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to sphinx-users...@googlegroups.com
> <mailto:sphinx-users...@googlegroups.com>.
> To post to this group, send email to sphinx...@googlegroups.com
> <mailto:sphinx...@googlegroups.com>.
> Visit this group at http://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/d/optout.

[Lenz Grimmer]

Hi juh,

thanks for your help. Using ".. include::" seems to work - I can put the file in ../common/Filename.rst and have a file in each document directory that just includes the actual document.
While it would be more elegant to directly reference the actual file in the toctree, this works for me.

Thank you!

Lenz

[Georg Brandl]

Am 25.03.2014 15:23, schrieb Lenz Grimmer:

> Hi,
>
> I've started using Sphinx by converting an existing OpenOffice Document into
> rst/sphinx (using od2sphinx). I now have a directory "FirstDocument", that
> contains all the relevant files, e.g. the Makefile, conf.py and the *.rst files
> that resemble this document.
>
> Now I'd like to create another document, let's call it "SecondDocument". I would
> like to be able to render both documents as individual PDFs. However,
> SecondDocument will contain a number of chapters that are part of the
> "FirstDocument" folder already.
> To avoid having to maintain the same files in two locations, I was thinking of
> creating a directory "common" on the same level as the directories for
> FirstDocument and SecondDocument and change the index.rst files in both
> directories to include these files by adding them as "../common/Filename.rst" in
> the toctrees. However, this does not seem to work, I get the following warning
> when running "make latexpdf" in the document directories: "WARNING: toctree
> contains reference to nonexisting document u'common/Filename' - the resulting
> PDF does not contain the chapters in question.

All files referenced by "toctree" must be within the project, i.e. the directory
containing conf.py and its subdirs. Within that, relative paths like
"../common/Filename.rst" are possible.

Note that Sphinx can already produce multiple .tex (and then .pdf) files from a
single project: the "latex_documents" config value is a list.

If you export to HTML, it is not advisable to have a single .rst file in two
different "toctree"s, since each .rst document can only have one set of
parent/predecessor/successor in the TOC tree.

But if you export only to LaTeX, it should work perfectly.

Otherwise, Jan Ulrich's suggestion with "include" is what you want.

cheers,
Georg

[Lenz Grimmer]

Hi Georg,

On Tuesday, March 25, 2014 5:55:23 PM UTC+1, Georg Brandl wrote:

All files referenced by "toctree" must be within the project, i.e. the directory
containing conf.py and its subdirs.  Within that, relative paths like
"../common/Filename.rst" are possible.

Note that Sphinx can already produce multiple .tex (and then .pdf) files from a
single project: the "latex_documents" config value is a list.

If you export to HTML, it is not advisable to have a single .rst file in two
different "toctree"s, since each .rst document can only have one set of
parent/predecessor/successor in the TOC tree.

But if you export only to LaTeX, it should work perfectly.

Otherwise, Jan Ulrich's suggestion with "include" is what you want.

Thanks a lot for your help - the hint about setting up multiple latex_documents was the key to success :)
I now have a conf.py, Makefile and contents.rst file in the toplevel directory (above the document directories). The toctree in contents.rst only contains references to the table of contents in each document's subdirectory. Shared chapters are in a "common" directory, which can now be referenced using "../common/" in the documents' toctrees. I created two separate documents in the latex_documents configuration, which generates independent PDFs.

Lenz

[juh]

Am 25.03.2014 17:55, schrieb Georg Brandl:
> Note that Sphinx can already produce multiple .tex (and then .pdf) files from a
> single project: the "latex_documents" config value is a list.

Too bad that it is not that easy with EPUB and other formats.

I must correct myself. You can use multiple configuration files but all
these files must have the name "conf.py". So if you want to use multiple
configuration files you have to create configuration folders first:

Like this:

doc-1/conf.py
doc-2/conf.py
doc-3/conf.py

Then you can call sphinx like this:

sphinx-build -b epub -c doc-1 sourcedir builddir/doc-1
sphinx-build -b epub -c doc-2 sourcedir builddir/doc-2
sphinx-build -b epub -c doc-3 sourcedir builddir/doc-3

to create eg. three different ebooks from one source.

juh