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:
- The stylesheet for the docs
- 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
Improve warning and info boxes' color, border and spacing
- 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
- 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
Improve applications page
Improve modules page
Add "progressive enhanced" syntax highlighting
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
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!