Website Contribution Manual

Welcome to the Website Contribution Manual! Your input is highly valued, and your efforts can enhance the overall quality of our documentation. Please follow the guidelines below for a smooth contribution process.

Set Up Project Environment

Setting up the project environment means configuring a working setup on your computer so you can edit the Nuitka website. To do so, use one of the following ways:

Manual Way

This is used to build the Nuitka website. Enhancements of all kinds are welcome. You will need Python 3.10 and pipenv to build it.

# Creates a virtualenv with all that is needed to develop the
# site.
python3 -m pip install -U invoke
python3 -m invoke virtualenv

# Now lets build the site, to see if it's all correct.
python3 -m invoke doc

# Optionally build the localized sites.
python3 -m invoke intl -l zh_CN
python3 -m invoke intl -l de_DE
...

# post-processing, e.g. adds language switcher, compact
# JS/CSS, adapts external links, and more.
python3 -m invoke run -t post-process

# Start local web server with the site, and do automatic
# rebuilds. Localization are rebuilt if they were previously
# built.
python3 -m invoke run -t serve-site

# Browse it (Linux)
xdg-open http://localhost:8080
# Browse it (Windows)
explorer http://localhost:8080

How We Work

In this section, we provide insights into our workflow and the tools we use to streamline our collaboration on the Nuitka website.

Sphinx

The Nuitka website is powered by Sphinx — a documentation generation tool widely used in the software development community. We use Sphinx to render user-friendly web pages for Nuitka, as the one you are looking at. To get more details about Sphinx, see Sphinx documentation.

reStructured Text (reST)

Sphinx uses reStructured text (reST) as its markup language, which is similar to Markdown but more powerful. You will need reST to edit pages of the website. Check out the syntax in the Sphinx documentation.

Sphinx Theme

We are using the customization of the Read the Docs Sphinx Theme. The current configuration is in shared_conf.py file is pretty basic. We might want to explore and document our choices for some of these options.

Sphinx Extension: Grids

We use Grids, a component of the Sphinx Design extension, to build the layout of our website pages.

Sphinx Extension: ABlog

We are using a Sphinx extension called ABlog to create the RSS feeds and pages of the Nuitka blog. To read about ABlog configuration options, see the ABlog documentation.

Document Formatting

In order to format the current document, in Visual Code, select the task autoformat current file which will make automatic changes to the file for consistent header formatting, etc.

All PRs should have their changed files formatted that way. We do not yet have a commit hook that does it.

Image Optimization

We optimize all the images we insert in the website to enhance website performance and achieve better search engine rankings. To optimize images, run the task autoformat PNG images or autoformat JPEG images or autoformat current file in Visual Code, the latter with the image being open.

Otherwise if you are not in the Dev Container, open a new terminal in the and paste the following code snippet.

# Optimize PNG files like this, normally not needed, this
# is lossless.
sudo apt-get install optipng
find . -iname *.png -a -type f -exec optipng -o7 -zm1-9 {} \;

# Optimize JPEG files like this, normally not needed, this
# is lossless.
sudo apt-get install jpegoptim
find . -iname *.jpg -a -type f -exec jpegoptim {} \;

Color Palette

If you create any visuals for Nuitka, such as presentation slides, diagrams, or even screenshots, keep in mind the following brand colors:

primary colors:

  • Blue #599DD2

  • Yellow #FFD43B

  • Grey #CCCCCC

secondary colors:

  • Dark Blue #2A3990

  • Green #00916E

Writing Style Guide

When writing any text on the Nuitka website, especially step-by-step guidelines, strive to follow the Microsoft Style Guide.

Opportunities for Contribution

In this section, you can see the ways to contribute to the Nuitka website.

Create a New Posting

To create a new page on the Nuitka website, do the following:

  1. Open Visual Studio Code, and then go to the Explorer tab to navigate to the directory of the project.

  2. Right-click on the directory where you want to create the new posting, then select New File. Or select Ctrl + Shift + P or (or Cmd + Shift + p for Mac).

  3. Name the file with the .rst extension. For example, my-new-posting.rst, obviously with a better name.

  4. Save the file by selecting Ctrl + S (or Cmd + S for Mac).

Translate Pages

You can help translate pages into your language.