Sphinx + autodoc + apidoc

[Ned Batchelder]

On Monday, October 24, 2016 at 7:02:11 PM UTC-4, Dan Stromberg wrote:
> On Mon, Oct 24, 2016 at 2:39 PM, Ned Batchelder <ned at 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.

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.