Improving Official Erlang Documentation
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!