Integration with Sphinx documentation project

[Byron Boulton]

I'm working on a project which has manuals, tutorials, release notes, technical documentation, and training slideshows.
I would like to have the training slideshows in the same sphinx project as the rest of my documentation, so I can build it all at once, so I get a project-wide index/glossary/search.
From what I read in the documentation this should be possible with hieroglyph, but I haven't figured out a way to put both document-type and slide-type materials into a single project.
Are there some examples of doing these somewhere?

Byron Boulton

[Nathan Yergler]

Hi Byron,

It is possible to use the same _source files_ to generate both slides
and documentation, but I'm not sure that's what you're looking for.
Sphinx includes several "builders" that take your source files and
emit some format: HTML, PDF, ePub, etc. Hieroglyph provides another
builder for making slides. So that means you can include slide
information along-side your documentation in the same file and
generate both, but it _doesn't_ mean you can say "hey, this file
should be a doc, this file should be a slide deck" (AFAIK).

Hope that helps!

NRY

> --
> You received this message because you are subscribed to the Google Groups
> "Hieroglyph Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to hieroglyph-use...@googlegroups.com.
> To post to this group, send email to hierogly...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Byron Boulton]

On Monday, February 1, 2016 at 12:58:15 PM UTC-5, Nathan Yergler wrote:
> Hi Byron,
>
> It is possible to use the same _source files_ to generate both slides
> and documentation, but I'm not sure that's what you're looking for.
> Sphinx includes several "builders" that take your source files and
> emit some format: HTML, PDF, ePub, etc. Hieroglyph provides another
> builder for making slides. So that means you can include slide
> information along-side your documentation in the same file and
> generate both, but it _doesn't_ mean you can say "hey, this file
> should be a doc, this file should be a slide deck" (AFAIK).

That's what I was afraid of. I guess I'll just continue by having a sphinx
project and a hieroglyph project and use intersphinx to link between the two.

I'm curious though, if we gave the slide documents a different file suffix
(maybe .slide.rst) could the sphinx configuration option `source_parsers
<http://www.sphinx-doc.org/en/stable/config.html#confval-source_parsers>`_
be used to parse these documents with the hieroglyph parser that creates html
slides?

Byron

[Nathan Yergler]

Sorry for the delayed reply, Byron.

Unfortunately I don't think the source parser is going to easily
address this. Hieroglyph/Sphinx/Docutils have separate parse and build
steps; the former (which is where a source parser would plug in) is
just responsible for taking a file and converting it to the internal
docutils representation. The builders are what actually output the
target format.

I suppose it might be possible to modify the hieroglyph _builder_ to
look at what the source extension was of documents it builds, and
either build slides or fall-back to the stock HTML behavior (ie, the
super class) depending on name/path/etc. That could be a solution.

NRY

[Byron Boulton]

Thanks for the insight. For now, what we have opted to do is distribute the presentation documents as regular documents with the usual documentation distribution. However, I modified the Makefile so that when I run `make slides` it only builds the top level index and the documents under a specific directory. Obviously the User Manual, and a number of other documents just don't work as slide presentations.

Byron