AlessandroMiola / website

PythonBiellaGroup official website

Python Biella Group: website

Official community website

⚡ Explore the website

Report Bug · Request Feature

Table of Contents

1. Intro
2. Features
3. Roadmap
4. How to maintain
5. Other informations and documentation

Intro

Official PythonBiellaGroup community website (WORK IN PROGRESS)

Features

In the PBG website you can find:

1. Home page and information about the community
2. List of all the past meetups
3. A reference, information and guide about python and tools
4. A blog with all the news about Python and the community

Roadmap

• Multilingual support
• Identify structure of the website sections
  • Home
  • Meetup (list of all meetup with video,keywords,contents) with tag
  • Wiki and articles section
  • Next events with calendar
  • Supporters section
  • Speakers section
• Learning section
• Quick feedback
• Cookies request form
• Migrate contents from old site
• Template folder for contents
• New home page
• New 404 page
• New CSS to improve design

(back to top)

How to maintain

Requirements

1. Remember to install the requirements for mkdocs plugins using brew installer if you are on MacOS

# On MacOs
brew install pngquant
brew install optipng

or on Linux

# on Linux
sudo apt-get install pngquant optipng

If you are using different operating system, please search online how to do it, open an issue in the repository or send a message to PythonBiellaGroup telegram channel.

WARNING: this libraries are available only for Linux and MacOs. If you are using Windows, setup and use WSL2 or Docker.

1. If you want to test and maintain the project locally, first you need to require the GITHUB TOKEN and GITHUB USERNAME that we are using for the project.

Please ask in the telegram group about it if you want to develop and contribute to the project.

For the admin: you can find the credentials in the PBG 1Password under the name: Github

When you have the credentials you have to create a .env file in the folder of the project with the following content (replacing <token> and <user> with the credentials you have received from the group):

GHCR_TOKEN=<token>
GHCR_USERNAME=<user>

This credentials are used to publish the website, use mkdocs-material-insight repository that we are using and sponsor, and to download the docker image from the registry.

1. Remember to install poetry because the python libraries and dependencies are managed with it.

(back to top)

Testing and developing

To launch the project locally you need to:

• Install the dependencies with poetry configuring the mkdocs-material-insight repository

source .env
poetry config http-basic.mkdocs ${GHCR_USERNAME} ${GHCR_TOKEN} && poetry install --with dev

With this instruction you are reading the .env file, configuring the repository and installing the dependencies with also the dev requirements.

• To launch the project you can use the Makefile with the command:

make docs_launch

• If you need to build the mkdocs artifacts to see the resources locally, you can use:

make docs_build

Please check the Makefile for more informations and commands.

(back to top)

Launching with docker

If you want to launch the website using docker and nginx you need to do few steps:

• Login to the docker registry to be able to download the base docker image we are using in the PythonBiellaGroup community that you can find here

source .env | docker login ghcr.io -u $GHCR_USERNAME -p $GHCR_TOKEN

• Using the Makefile and docker-compose you can now launch directly the website, downloading the image, installing the libraries with poetry and passing the artefacts to a second stage container with nginx that it's service the website on the port 8044

make docker_launch

Remember that in this step it's used the .env file to access to the github registry to use mkdocs-material-insight repository.

• After few seconds you are able to see the website to the address: http://localhost:8044

Remember at the end to logout from docker registry if you are not using it anymore:

docker logout ghcr.io

(back to top)

Check before commit

Inside the repository we are using pre-commit to check the quality of the code.

Pre commit it's automatically installed and added inside the repository.

Before committing something launch the command to check the code quality:

# Precommit check launch with mkdocs
make check_project

# Precommit check launch with just
just check_project

If you are not launching this 2 commands before pushing something you risk to not pass pre-commit checks and you will have to commit again because automatically pre-commit will fix the problems in the repo.

(back to top)

Release a new version of the website

To publish the project you need to make a new GITHUB RELEASE going on the webpage of the project.

Create a new release with a new tag, for example:

• Release name: Release 0.0.5
• Tag: 0.0.5

Remember to fill all the information of the new release in the description and then Release the new package.

Automatically the new pipeline will start.

Please remember to test before following the steps in Building the project

Remember also that only the admins and organizer can make a new release.

(back to top)

Other informations and documentation

General link and documentation

• Multilanguage support on mkdocs
• Good tutorial on multilanguage support

Examples

• The blue book
• Ludwing website
• UP24 SDK
• AWS Copilot CLI
• Ultrabug

Mkdocs useful tutorials

• Meta plugin mkdocs
• Blog plugin mkdocs
• Use environmental variable in Mkdocs
• Mkdocs official blog post on how it's working
• Add comments to the blog posts

Interesting plugins

• Mkdocs macros plugin
• Mkdocs redirect
• Mdocks plus

(back to top)