[doc] Sphinx.

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

[doc] Sphinx.

Boost - Build mailing list
Ok, looking at the features of Sphinx more closely now.. Since there are various people here knowledgeable about Sphinx.

First question: Does Sphinx support PDF output *without* going through another output tool (i.e. not through docbook or latex)?

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Sphinx.

Boost - Build mailing list
Le 09.08.17 à 04:02, Rene Rivera via Boost-build a écrit :
> Ok, looking at the features of Sphinx more closely now.. Since there are
> various people here knowledgeable about Sphinx.
>
> First question: Does Sphinx support PDF output *without* going through
> another output tool (i.e. not through docbook or latex)?

I believe not: they claim to generate Latex. But being able to generate
Latex is more than enough for the PDF output, isn't it?

What is your point?

Raffi

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Sphinx.

Boost - Build mailing list
On Wed, Aug 9, 2017 at 12:53 AM, Raffi Enficiaud via Boost-build <[hidden email]> wrote:
Le 09.08.17 à 04:02, Rene Rivera via Boost-build a écrit :
Ok, looking at the features of Sphinx more closely now.. Since there are
various people here knowledgeable about Sphinx.

First question: Does Sphinx support PDF output *without* going through
another output tool (i.e. not through docbook or latex)?

I believe not: they claim to generate Latex. But being able to generate Latex is more than enough for the PDF output, isn't it?

I don't know Latex (even though I edited some latex some decades ago) so all I can go by is what others claim it does.

What is your point?

My point is that if that's the only option for PDF it's similar to quickbook in that it needs another tool to be installed. Having to install and correctly set up external tools raises the barrier to producing the good looking PDF docs. Something we are all too familiar with docbook. For example, I've tried two or three times over the past decade to get PDF output working for docbook without success.


--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Sphinx.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On Tue, Aug 8, 2017 at 9:02 PM, Rene Rivera <[hidden email]> wrote:
Ok, looking at the features of Sphinx more closely now.. Since there are various people here knowledgeable about Sphinx.

More questions..

Does Sphinx support output to docbook? 

Does Sphinx support *configurable* HTML output? I.e. can I use my own HTML templates directly to change the output structure and style?

Note, feel free to answer with just links to their documentation. As I'm finding it hard to navigate their docs (Yes I realizes how that sounds).

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Sphinx.

Boost - Build mailing list
 
> Ok, looking at the features of Sphinx more closely now.. Since there are various people here knowledgeable about Sphinx.
> More questions..
> Does Sphinx support output to docbook? 
Not natively, but it should be possible to write a converter: https://github.com/HolgerPeters/sphinxcontrib-docbook
I think the basic process is to run sphinx with the XML builder and then transform that XML to docbook XML.
My question would be: why do this?
Is this for PDF support?
It looks like there is a builder that can be used to produce PDF output: https://github.com/brechtm/rinohtype
However, it requires Python3.3+
 
How important is PDF support? Just curious as I typically only use HTML for documentation.
 
> Does Sphinx support *configurable* HTML output? I.e. can I use my own HTML templates directly to change the output structure and style?
Yes. You can create your own theme and use that: http://www.sphinx-doc.org/en/stable/theming.html
Some existing sphinx themes: http://www.writethedocs.org/guide/tools/sphinx-themes/
 
Aaron
 

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Sphinx.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
Le 09.08.17 à 14:14, Rene Rivera via Boost-build a écrit :

> On Wed, Aug 9, 2017 at 12:53 AM, Raffi Enficiaud via Boost-build
> <[hidden email] <mailto:[hidden email]>> wrote:
>
>     Le 09.08.17 à 04:02, Rene Rivera via Boost-build a écrit :
>
>         Ok, looking at the features of Sphinx more closely now.. Since
>         there are
>         various people here knowledgeable about Sphinx.
>
>         First question: Does Sphinx support PDF output *without* going
>         through
>         another output tool (i.e. not through docbook or latex)?
>
>
>     I believe not: they claim to generate Latex. But being able to
>     generate Latex is more than enough for the PDF output, isn't it?
>
>
> I don't know Latex (even though I edited some latex some decades ago) so
> all I can go by is what others claim it does.

I believe that, if you are in the point that you need to edit the latex
of the generated Sphinx, there is something wrong in the workflow.

Yes, you will need to install Latex, but I prefer that rather than
Sphinx ppl spending 80% of their resources on writing code that
generates correct PDF files.

The only interface is:

 > make latexpdf

and this is calling pdflatex with the right options for you. It requires
latex to be installed, as well as python of course, and make, a shell,
etc...

>
>     What is your point?
>
>
> My point is that if that's the only option for PDF it's similar to
> quickbook in that it needs another tool to be installed. Having to
> install and correctly set up external tools raises the barrier to
> producing the good looking PDF docs. Something we are all too familiar
> with docbook. For example, I've tried two or three times over the past
> decade to get PDF output working for docbook without success.

This is not exactly similar. I have very little expertise in docbook,
but when I see this:

https://stackoverflow.com/a/4728751/1617295

this looks like a nightmare, and needless to say it works well only on
OSes that have very good committed package maintainers :)

(Now it sounds that I need to defend Latex :D )

Latex is available in on many OSes, is very well maintained and has a
quite large set of users (95% of the scientists I know use latex, the
others: I flag them as non-scientists anyway).

I believe this is not such a bad design that Sphinx decided to output
Latex to generate PDF, because this looks to me like the "shortest path"
to correct and good PDF.
Docbook OTOH decided not to do that, and ends up using a "longer path"
(more tool involved), that is also more fragile (setup, maintenance,
documentation).

In a previous post, you claimed that
"""
Popularity is not a wining argument around here ;-)
"""

I disagree:
* latex is popular in its own community, as a consequence, it is easy to use
* sphinx is popular in its own community, as a consequence, it is easy
to use and to interface with latex
* docbook is not popular, as a consequence, the toolchain is weak and
stayed so until now (and is de facto an impediment to its popularity).

You may see popularity as a cause or a consequence: it is both, and
often it over weights the technical aspects on the long run.

*BUT* my claim "docbook vs. Sphinx" is not this at all. Docbook is hard
to use, that is a given or an opinion.
The main rant I have against docbook is the markup, that basically needs
a software more complex than just a text editor to be of any good usage,
and is otherwise error prone, verbose, and requires a look of tweaking
to have a decent output. All those facts made on average more work,
either to editors that want to create documentation, or to developers
that need to cover all the shortcomings of docbook with another layer
(such as boostbook or quickbook).

*IF* you take "expressivity for content creation" argument first, and
then suddenly need to generate PDF output, then one candidate is able to
do it easily and almost seamlessly, the other one is adding new problems
on top, but is still able to do it. In terms of features, they are
equivalent though, just developers' life is different. The decision path
for equivalent features would be: let's try to ease my file.

*IF* you take the same argument first, and now compare Sphinx to
ASCIIDOCTOR, then which one gives you most flexibility and degrees of
freedom for the output? is PDF possible or well integrated to Asciidoctor?

But tackling the problem the opposite direction (ie: "needs extra tool
to generate PDF => so not good") is not the right decision pattern for me.

Best,
Raffi

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Sphinx.

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On 8/9/2017 9:12 AM, Aaron Boman via Boost-build wrote:
 
> Ok, looking at the features of Sphinx more closely now.. Since there are various people here knowledgeable about Sphinx.
> More questions..
> Does Sphinx support output to docbook? 
Not natively, but it should be possible to write a converter: https://github.com/HolgerPeters/sphinxcontrib-docbook
I think the basic process is to run sphinx with the XML builder and then transform that XML to docbook XML.
My question would be: why do this?
Is this for PDF support?
It looks like there is a builder that can be used to produce PDF output: https://github.com/brechtm/rinohtype
However, it requires Python3.3+
 
How important is PDF support? Just curious as I typically only use HTML for documentation.
 
Please let PDF die, like Flash. :) I hate that R's documentation and vignettes, before downloading a package, are almost entirely rendered in PDFs.

-Matt

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Loading...