Improving Official Erlang Documentation

Mariano Guerra — Sun, 23 Oct 2016 21:55:49 GMT

Many times I've heard people complaining about different aspects of the Official Erlang documentation, one thing that I find interesting is the fact that the Erlang documentation is really complete and detailed, so I decided to dedicate some time to other parts, to get familiar with it I decided to start with an "easy" one, it's presentation.

So I downloaded erlang/otp:

git clone https://github.com/erlang/otp.git

And did a build:

# to avoid having dates formated in your local format
export LC_ALL="en_US.utf-8"
cd otp
./otp_build setup
make docs

Then I installed the result in another folder to see the result:

mkdir ../erl-docs
make release_docs RELEASE_ROOT=../erl-docs

And served them to be able to navidate them:

cd ../erl-docs
python3 -m http.server

If you want to give it a try you need to install the following deps on debian based systems:

sudo apt install build-essential fop xsltproc autoconf libncurses5-dev

With the docs available I started looking around, the main files to modify are:

lib/erl_docgen/priv/css/otp_doc.css: The stylesheet for the docs
lib/erl_docgen/priv/xsl/db_html.xsl: An XSLT file to transform xml docs into html

The problem I found at first was that to see the results of my changes to db_html.xsl I had to do a clean and build from scratch, which involved recompiling erlang itself, taking a lot of time.

Later I found a way to only build the docs again by forcing a rebuild:

make -B docs

But this still involves building the pdf files which is the part that takes the most time, I haven't found a target that will only build the html files, if you know how or want to try to add it in the make file it would be great.

With this knowledge I started improving the docs, I will cover the main things I changed.

You can see all my chages in the improve-docs-style branch.

Small styling changes

Don't use full black and white
Set font to sans-serif
Use mono as code font
Improve link colors
Improve title and description markup on landing page
Update menu icons (the folder and document icons)
Improve panel and horizontal separator styles
Align left panel's links to the left

Improve code box color, border and spacing

Old Code Examples

New Code Examples

Improve warning and info boxes' color, border and spacing

Old Warning Dialog

New Warning Dialog

Old Info Dialog

New Info Dialog

Logo Improvements

Remove drop shadows from logo
Center Erlang logo on left panel
Erlang logo is a link to the docs' main page
Put section description after logo and before links in left panel

Old Landing Page

New Landing Page

Semantic Improvements

Use title tags for titles
Remove usage of <br/> and empty <p></p> to add vertical spacing
Use lists for link lists
Title case section titles instead of uppercase
Add semantic markup and classes to section titles and bodies
Add classes to all generated markup
- The ones I couldn't figure out a semantic class I added a generic one to help people spot them in the xsl document by inspecting the generated files
Clicable titles for standard sections with anchors for better linking

Improve table styling

Old Tables

New Tables

Improve applications page

Old Applications List

New Applications List

Improve modules page

Old Modules List

New Modules List

Add "progressive enhanced" syntax highlighting

At the bottom of the page there's a javascript file loaded, if successful it will load the syntax highlighter module and css and then style all the code blocks in the page, if it fails to load, is blocked or no js is enabled then the code blocks will have a default styling provided by CSS.

The markup was not modified in any way to add this feature.

Make code tokens easier to differentiate from standard text

The previous style for inline code was a really light italic font, I changed it to monospace but it was hard to distinguish, so I got some inspiration from slack and surrounded the inline code words in a light box to make them stand out.

Indent Exports and Data Types' section bodies

Old Data Types and Exports Sections

New Data Types and Exports Sections

This is all for now, I have some other ideas for future improvements but they involve changes to the documentation so I will submit them separatedly.

If you have any feedback please let me know!

mozilla rhino 1.7R3 javadocs apidocs mirror

Mariano Guerra — Thu, 01 Dec 2011 12:38:00 GMT

hasta que los muchachos de mozilla arreglen sus links rotos y suban de nuevo los javadocs de mozilla rhino este humilde servidor las postea aca

http://marianoguerra.com.ar/docs/rhino-1-7R3/index.html

PD: SEO friendly title :P

Mariano Guerra's Log (Posts about docs)