Prettifying the docs

[danielcompton]

Hi Tom

What are your thoughts about prettifying Autodoc, particularly with adding mobile support?

Would you accept a patch for this? Do you have any technical or design restrictions around this, e.g. use of JavaScript or CSS?

[tomfaulhaber]

Hi Daniel,

I am very open to prettifying the docs and would be happy to accept a patch that made substantial progress there. I think it would be best if we developed an approach with examples rather than just dropping a single big patch for it so we converge on the "right thing".

Some background that will help me answer your questions. When I created autodoc (way back when), I had two goals from the formatting. First, I wanted to make the doc site match clojure.org in look and feel. Secondly, I wanted folks to be able to download a simple tree and have access to the docs offline.

The second of these goals still seems appropriate, but I might soften the first goal to be something more like "feels consistent with clojure.org" rather than "matches clojure.org."

Another factor that went into the design was that I didn't want to be prescriptive about how people wrote doc strings (because I didn't think it would work), but rather capture and present doc strings in the best possible way given how they actually appear in the wild. Thus I was kind of forced into monospace for the doc strings themselves.

As a result of these decisions, the CSS is a mangled extension of the already mangled stuff that the wikispaces thing that clojure.org used and I rejected any Javascript at all.

I would love to see the CSS just get redone from the ground up and am open to adding Javascript for functionality though I would prefer that we're not completely generating the pages a la React for accessibility and simplicity. (One thing I would love to see is a search capability.)

We need to think about workflow if we use something like less because the pages should support the Github Pages push and batch download for off-line viewing case.

Additionally, we should add @puredanger to this discussion so that he can represent any opinions of the clojure core team.

When thinking about the reformat, we should look at the Python and Scala docs as well as other Clojure and Javascript documentation engines and try to learn from all of them.

• Tom

[danielcompton]

Hi Tom

That all sounds good. Could you expand on

I think it would be best if we developed an approach with examples rather than just dropping a single big patch

and this:?

able to download a simple tree

What is a simple tree here? I'm assuming you mean you can download a single page which contains everything required?

[danielcompton]

Also, I recall @puredanger mentioning that there is a new Clojure website coming, it would probably be good to design to match the new website, not the old one :)

[puredanger]

There is nothing imminent.

[tomfaulhaber]

I think it would be best if we developed an approach with examples rather than just dropping a single big patch

What I mean here is that we should create a new CSS/Javascript environment, preview it, and iterate over some feedback before applying it. That said, there's no reason we can't do things incrementally. For example, we can "reform" the CSS to be better looking as one step and then add more smarts (search, etc.) in stages.

able to download a simple tree

What is a simple tree here? I'm assuming you mean you can download a single page which contains everything required?

Exactly.