Docstrings contain line breaks whenever the source comments contain line breaks

[KesterTong]

Common conventions for source code require line breaks every 80 characters. But doing so induces line breaks in the docstring which is not necessarily desired. E.g. in the source code

||| This module defines a generalized algebraic data type, `MessageDescriptor`,
||| which is the strongly typed equivalent of the `Descriptor` protocol buffer.

The line breaks result in a docstring with line breaks.

I believe that the best approach is to interpret the above comment as the following markdown:

This module defines a generalized algebraic data type, `MessageDescriptor`,
which is the strongly typed equivalent of the `Descriptor` protocol buffer.

which should ignore the line breaks since only double line breaks should be interpreted as real line breaks. (note, Github flavored markdown treats a single line break as a line break, but most other markdown processors don't).

[melted]

cheapskate has an option to turn off the linebreaks, so it would be an easy thing to do. But how many of our docs use this assumption and would look bad?

[KesterTong]

I took a quick look and it seems like few docs rely on these hard line breaks for formatting. In some cases minor changes would be needed like adding missing periods. On the other hand, with the current CSS, putting everything on one line can result in very long lines that are hard to read (e.g. 166 chars). I attached an image with the original docs, updated docs, and updated docs with changes to CSS to make the font size 12pt (for text only) and the left and right margins equal. To me the version with updated CSS is easier to read.

I'm happy to go through the docs and make the needed fixes, and update the doc generation code and CSS, as long as you're not in a great hurry (eta 1-2 months as I have to learn how to build Idris and the docs). If so feel free to assign the issue to me.

• original docs
• docs with no hard line breaks
• docs with no hard line breaks and updated CSS

[melted]

That sounds like a nice project! Don't worry about it taking time.

[KesterTong]

Thanks @melted I will start on this. I have a few questions.

1. The docs I showed above were from http://www.idris-lang.org/docs/. Is this the right place to be looking? These docs don't seem to be linked by http://docs.idris-lang.org/en/latest/
2. How to build the library docs? It looks like make lib_doc builds the docs for the Idris Haskell packages and make user_doc builds http://docs.idris-lang.org/en/latest/ which doesn't contain the library docs.

[jfdm]

@KesterTong

IIRC the IdrisDoc pages on http://www.idris-lang.org/docs are put their manually, and are not linked to the readthedocs pages.

For building documentation:

• make doc builds the haddock
• make lib_doc builds the Idris doc for packages in lib/
• make user_docs builds the sphinx user documentation.

Any more questions just ask.