Sphinx + autodoc + apidoc

[Dan Stromberg]

Hi folks.

I'm attempting to set up Sphinx to document several API's based on docstrings.

I've got something browseable for one example API using Sphinx +
autodoc + apidoc.

However, we aren't really a PEP8 shop; we use hard tabs expanded to 4
columns, and we use 120 columns total width (and sometimes a little
more :).

I'd love to switch to spaces, but it's not my decision, so... And
it's hard for me to imagine going back to 80 columns - it's so
confining, especially when you use good, descriptive identifiers.

Anyway, in the Sphinx pages that say "Source code for <modulename>",
and that show every line of the particular python module (syntax
highlighted), the tabs are all expanded to 8 columns, and the total
width is 80 columns. I can scroll around to see everything, but it's
a little like looking at a football field through a microscope.

Is there any good way of making Sphinx use 4 column tabs and 120 column text?

I can imagine recursively applying *ix "expand -4" to the .py files to
get a for-doc-only tree before passing them to Sphinx, but what about
the 80 column limit? And is there a nicer way of dealing with the tab
situation?

I googled quite a bit, and found some stuff suggesting that the Sphinx
devs would be OK with doing hard tabs, but Sphinx depends on Docutils,
and the Docutils project is perhaps more into PEP8.

Thanks!

[Ned Batchelder]

Are you sure your tabs are being changed to eight spaces? It's possible they
are still tabs in the browser, and the browser is choosing to display them
as eight spaces. If that's the case, you can change the width using CSS in
the theme. Likely the page width of 80 characters is also manipulable with
CSS.

--Ned.

[Dan Stromberg]

On Mon, Oct 24, 2016 at 2:39 PM, Ned Batchelder <n...@nedbatchelder.com> wrote:
> On Monday, October 24, 2016 at 5:00:47 PM UTC-4, Dan Stromberg wrote:

>> However, we aren't really a PEP8 shop; we use hard tabs expanded to 4
>> columns, and we use 120 columns total width (and sometimes a little
>> more :).

>> Is there any good way of making Sphinx use 4 column tabs and 120 column text?

> Are you sure your tabs are being changed to eight spaces? It's possible they
> are still tabs in the browser, and the browser is choosing to display them
> as eight spaces. If that's the case, you can change the width using CSS in
> the theme. Likely the page width of 80 characters is also manipulable with
> CSS.

It turned out CSS was the answer. I fixed it with:

echo 'pre {tab-size: 4;width: 80em;}' > doc/_build/html/_static/custom.css
echo 'div.document {width: 100em; margin-top: 0px; margin-bottom:
0px; margin-right: 0px; margin-left: 0px;}' >>
doc/_build/html/_static/custom.css

Though it remains to be seen if it'll look as good in other people's
browsers. It bothers me that 120 columns of text fit so easily into
80em. I thought 80em would be the width of 80 character cells... It
seems like a fixed pitch font, but maybe it's really proportionate.
Using 120em was huge.

Thanks!

[Ned Batchelder]

An em is a unit as wide as the font size. So with 12-point text, an em
is 12 points wide. Most characters are much narrower than that. The unit is
called "em" because it's roughly the width of a capital M in a proportional
font. Your monospace font would have 80 characters in 80em if the
characters were all square, but they are not. Much more common is a
character width of about .6em.

Typography has a long history spanning multiple technologies, and close
connections with people and how they read, so it isn't always obvious,
though I personally find it fascinating.

--Ned.