[sphinx-dev] Included non-rst files not copied to _source directory
TP
"If you want to use some substitutions for all documents, put them into
a separate file and include it into all documents you want to use them
in, using the include directive. Be sure to give the include file a file
name extension differing from that of other source files, to avoid
Sphinx finding it as a standalone document."
However, if you DO name your included file with an extension other than
.rst (say .hr), it will NOT be copied over to the _build/html/_sources
directory.
Additionally, in the latest trunk revision, the unused_docs conf.py
option no longer works, so if you change the name back to include .rst,
you then get the "WARNING: document isn't included in any toctree"
message.
If instead you add the file to the new exclude_patterns option, then
again it no longer gets copied to the _sources directory.
Max Battcher
> Additionally, in the latest trunk revision, the unused_docs conf.py
> option no longer works, so if you change the name back to include .rst,
> you then get the "WARNING: document isn't included in any toctree"
> message.
That warning is certainly harmless, if that's your biggest concern
against using .rst as the file extension. In an earlier thread Georg
mentioned that maybe it was time that warning was rewritten or
rethought, because it looks scarier than it is intended to be. From what
it appears to me, it's meant to be something of a "Hey, did you know you
didn't add this file to your toctree?" reminder than a "Whoops, things
are broken because you have a document that you haven't put into a
toctree." I think that maybe the documentation you cited should be
rewritten as well.
--
--Max Battcher--
http://worldmaker.net
TP
However, as described in my "Include directive doesn't correctly support
'absolute' paths" message, includes seem to be useless when used from
multiple subdirs in the same project.
Unless I'm missing something, there doesn't seem to be any easy way to
use the same include directive from multiple subdirs. You might be able
to use different 'relative' paths depending on where you are including
from but that seems more bother than it's worth.
Instead, for now, I'll just implement a rst-prologue conf.py option
(analogous to the rst-epilog option) and avoid includes altogether.
> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-dev" group.
> To post to this group, send email to sphin...@googlegroups.com.
> To unsubscribe from this group, send email to
> sphinx-dev+...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/sphinx-dev?hl=en.
>
>
Fernando Perez
>
>
> However, as described in my "Include directive doesn't correctly support
> 'absolute' paths" message, includes seem to be useless when used from
> multiple subdirs in the same project.
>
> Unless I'm missing something, there doesn't seem to be any easy way to
> use the same include directive from multiple subdirs. You might be able
> to use different 'relative' paths depending on where you are including
> from but that seems more bother than it's worth.
>
> Instead, for now, I'll just implement a rst-prologue conf.py option
> (analogous to the rst-epilog option) and avoid includes altogether.
My (hackish, ugly but functional) solution to this is to use
include: foo.txt
and in *every* directory (but the project topmost one, of course),
have a symlink
foo.txt -> ../foo.txt
so they eventually all resolve at the top. Not pretty, but works for me :)
Cheers,
f
TP
http://bitbucket.org/tpowers/sphinx/changeset/c5ad17aa65cb/ (it's only
a few changed lines).
Purnank Ghumalia
I tried the same, but its not that easy!
When docutils generates warnings, I found that the generated warnings
were always at an offset.
e.g. docutils says error at line 10, but physically, its line 2 in
your .rst file.
BR,
Purnank
On Mar 30, 5:35 pm, TP <wing...@gmail.com> wrote:
> I implemented rst_prologue option in conf.py here:http://bitbucket.org/tpowers/sphinx/changeset/c5ad17aa65cb/(it's only
> a few changed lines).
>
> On Mon, Mar 29, 2010 at 7:29 PM, Fernando Perez <fperez....@gmail.com> wrote: