30. 10. 2024
Automation, Development, Documentation
During this release we worked a lot to improve the NetEye User Guide.
The new user guide is now independent of the NetEye product itself, it can be found online and its structure is greatly changed. By this I mean that we improved not only its content, but we also decided to use a more suitable tool for creating intelligent and beautiful documentation. The NetEye User Guide is now built with Sphinx.
Sphinx is a powerful documentation generator that has many great features for writing technical documentation including:
- Generation of web pages and PDFs, both generated from the same source
- Support for both reStructuredText and Markdown formats when writing documentation
- An extensive system for cross-referencing code and documentation
- Syntax-highlighted code samples
The Sphinx tool is highly customizable with plenty of extensions and themes, which was one of the main reasons why we decided to use it. Nevertheless, we preferred to create our own NetEye theme from scratch in order to meet all the design and usability requirements that we had.
Here for example are some of them:
- The top bar and the sidebar should look like the ones in NetEye – we wanted to give the impression of being in NetEye itself while reading the documentation
- The search bar should be easy to find, so we decided to put it in the top bar
- We also needed to enable switching between different NetEye versions, in order to give users the opportunity to find the appropriate documentation for their current NetEye installation
- The homepage should be attractive and should describe the product structure at a glance
- The content should be well organized and easily readable, and so we decided to improve the local page’s ToC, making it follow the page scroll; the content should also be responsive so that it can also be read on mobile devices, and code-blocks should be correctly highlighted with code content that can be copied to help users with commands
In this blog I will describe how, starting from the basic Sphinx theme, we were able to create our custom one. Here you will find some basic techniques for customizing the HTML template.
Step 0: Set up the Theme Folder
We created our NetEye folder inside the theme folder in the build directory of our Sphinx project. Inside this directory we then add all necessary files.
One of the first files needed to make Sphinx detect your custom theme is theme.conf. Here you should define its main features. For example we set:
[theme]
inherit = classic
stylesheet = neteye.css
pygments_style = none
sidebars = globaltoc.html
globaltoc_includehidden = true
globaltoc_collapse = false
globaltoc_depth = 2As you can quickly see from this example, you can for instance link to the stylesheet, set all the HTML files that will compose your sidebar, and define the menu levels that will be displayed there.
Step 1: How to Include Bootstrap
We wanted to use Bootstrap in order to take advantage of all its responsive resources and cool components. To do this we:
- Created a
static/folder intheme/neteye/, where we installed both the .cssand .jsfiles from the Bootstrap library - We created our own
layout.htmlfile intheme/neteye/and extended Sphinx’s basic theme
Here’s how we included Bootstrap .css and .js in our layout.html file
{%- extends "basic/layout.html" %}
{% set css_files = css_files + ['_static/bootstrap.min.css'] %}
{% set script_files = script_files + ['_static/bootstrap.min.js'] %}The documentation really doesn’t look like Bootstrap any more. To achieve this we had to add the correct classes in order to add style and responsiveness.
Step 2: How to Customize Blocks and Macros
If you’ve ever taken a look at the Sphinx documentation, you probably already know that there are some fixed page components that Sphinx renders when creating the HTML page. You can overwrite and customize them.
Let’s start by seeing how to easily overwrite a macro.
To be consistent with our design mockups, we had to, for example, create a completely custom HTML breadcrumbs component.
We saved the breadcrumb.html file in theme/neteye/ folder, and we structured this component as follows:
<ol class="breadcrumb">
<li class="breadcrumb-item">
<a href="{{ pathto(master_doc) }}">
{{ shorttitle|e }}
</a>
</li>
{%- for parent in parents %}
<li class="breadcrumb-item">
<a href="{{ parent.link|e }}"
{% if loop.last %}
{{ accesskey("U") }}
class="active"
{% endif %}>
{{ parent.title }}
</a>
</li>
{%- endfor %}
<li class="breadcrumb-item active">{{ title }}</li>
</ol>This way, the breadcrumbs component behaves exactly as the Bootstrap one does. We then overwrote the default one to include the following lines of code in our layout.html file
{% macro breadcrumb() %}
{% include "breadcrumb.html" %}
{% endmacro %}It may happen that you don’t need to completely overwrite a component, you just have to customize it for example by adding classes. It happened to us like this for the content block. Here’s an example of what we did to achieve our goal and convert this static block into a responsive Bootstrap container:
{%- block content %}
<div id="main-container" class="container-fluid">
<div class="row">
{{ super() }}
{% endblock %}Step 3: Include Custom Fonts and Custom JavaScript Files
The previous steps can help you understand how you can easily create your own theme, with a complete custom HTML structure.
This obviously doesn’t ensure that the style is exactly as you expect, but you can always improve it using some custom CSS files, fonts, or JavaScript files. Here’s how you can include them in the proper sections:
{%- block css %}
<link href="{{pathto('_static/roboto.css', 1)|e}}" rel="preload" as="style">
{{ super() }}
{%- endblock %}
{%- block scripts %}
<script src="{{pathto('_static/neteye.js', 1)|e}}" async></script>
{{ super() }}
{%- endblock %}Following the steps described in this blog post, you can reach a pretty good level of customization, but if you need some more advanced techniques for creating custom effects or components, take a look at this blog post, too. You will surely find some other interesting hints on how you can turn the static Sphinx HTML page into a good looking, modern site.
Valentina Da Rold
Hi, I'm Valentina and I'm a Frontend Developer at Wuerth Phoenix. I started out my career applying my Cryptography skills to coding, but really quickly fell in love with the web. I have been making websites and applications since 2012 and I still can't get enough of it. Along the way I found a passion for front-end development, and I use this passion to create interfaces that solve problems. When I'm not creating beautiful solutions, I enjoy cooking or doing sport, while listening to beautiful music.
Author
Latest posts by Valentina Da Rold
26. 11. 2024
Atlassian, Development, UI, UX
How to Customize Your Barcode Scanning App (Part 1)
14. 11. 2024
Atlassian, Service Management
Take Control of Your Assets from Anywhere with Just a Wave of Your Hand!