docs.pelican.bernatchez.net

Configure a New Bunny Site

2026-05-09T12:59:29+00:00

Example steps to set up a your bunny.net account to accomodate a new site.

In this example Our new site called: dummy.example.net

Change your names according to your site name.

login to your bunny.net account at: https://dash.bunny.net/
create a standard storage zone named: dummy-example-net [1]

[1]	Picture shows "docs-pelican-bernatchez-net" should show "dummy-example-net"

create a pull zone named: dummy-example-net-zone [2]

[2]	Shows "docs-pelican-bernatchez-net-zone" should show "dummy-example-net-zone"

login to your DNS service account.
On your DNS server create a record: dummy.example.net CNAME dummy-example-net-zone.b-cdn.net
Back on bunny.net add a custom hostname dummy.example.net to the pull zone [3]

[3]	Shows "docs.pelican.bernatchez.net" should show "dummy.example.net"

When you do this add, take the opportunity to confirm certificate is working.

Now your site is ready to serve. You can publish to it.

Getting it on one page

2026-04-26T01:36:19+00:00

My recipes consist of an image and the instructions to prepare it beneath that. For the sake of ".pdf" printing, I try to fit it all in a sindle page. That means I must keep the image small.

In practical terms, I take a picture with my cell phone. Then I open that up with the shotwell viewer and I crop the part I want from it.

Then whatever I end up with, I shrink to about 1000 pixels wide.

shrink command

convert original.jpg -resize 1000x pagefit.jpg

snippet that includes the image in the RST source

|

.. image:: ../images/pagefit.jpg
    :class: img-responsive
    :scale: 30%
    :alt: The result

I have included such an image above as illustration.

Creation of a .rst site

2026-04-16T01:47:25+00:00

We go through the process of creating a new site subdirectory in our git repository here to record a walk through of starting a new site.

For the actual creation of hosting infrastructure within a bunny.net account see: newbunny site

mypelican_static_sites is the git repository project where we set it up.

We make a new site is called: dummy.bernatchez.net

Create the new site directory and populate it

# create
cd ${HOME}/repos/mypelican_static_sites
mkdir dummy.bernatchez.net

# populate
cp -r -P init.files/* dummy.bernatchez.net/

reference the pre-existing pelican/ articles within our dummy site

You only need for the directory to exist under content/ for that. The Makefile takes care of populating the subdirectory.

We will add a placeholder.txt file in that directory so that git clone will create the subdirectory in the future.

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net
mkdir content/pelican

# this assures pelican/ directory is created henceforth upon git clone
cp content/pages/placeholder.txt content/pelican/placeholder.txt
git add content/pelican/placeholder.txt

Add the following lines to the end of ".gitignore"

cd ${HOME}/repos/mypelican_static_sites

cat >>.gitignore <<EOFGITIGNORE
##
## BEGIN added for a new site
##

# dummy.bernatchez.net softlinks

dummy.bernatchez.net/content/favicon.ico
dummy.bernatchez.net/content/images/
dummy.bernatchez.net/content/site-only/
dummy.bernatchez.net/content/pages/
dummy.bernatchez.net/content/pelican/

dummy.bernatchez.net/content/images/*
dummy.bernatchez.net/content/site-only/*
dummy.bernatchez.net/content/pages/*
dummy.bernatchez.net/content/pelican/*


# dummy.bernatchez.net bucket is all generated
dummy.bernatchez.net/bucket/
dummy.bernatchez.net/bucket/*

##
## END additions for a new site
##
EOFGITIGNORE

cd ${HOME}/repos/mypelican_static_sites
git add .gitignore

Put the customizable files under version control

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net

git add Makefile
git add deploy.bunny
git add favicon.ico
git add login.bunny
git add names.bunny
git add notes.txt
git add pelicanconf-en.py
git add pelicanconf-es.py
git add pelicanconf-fr.py
git add publishconf-en.py
git add publishconf-es.py
git add publishconf-fr.py
git add purge.bunny
git add puta2p.sh

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/pages
git add *.rst

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/content
git add binaries images sitepdfs

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/pages-media
git add *

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/pages-pdfs
git add placeholder.txt

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/site-only-pdfs
git add placeholder.txt

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/site-only
git add *.rst

# Commit your git additions

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/
git commit -m new-dummy-site

Generate this first revision of the site

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/
make html

# revise and continue maintaining as and when required

Once you are satisfied with the site generate a publishable version

This relies on the bunny.net storage zone and pull zone existing otherwise the deploy.bunny step will fail.

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/
make pubhtml

Welcome Message

2026-03-22T00:38:24+00:00

Welcome to this site.

This site is intended to support, with documentation, anyone maintaining the source for the pelican generated web sites contained in our git repository. This site in intended to be unpublished, only viewed from the local file system.

Contacts

2026-03-22T00:34:39+00:00

Please address all queries to the current site administrator.

Current Site Administrator

pierre@bernatchez.net

About

2026-03-22T00:29:07+00:00

Site Version

2026-05-10T00:29:55+00:00

Description

The site is organized like a blog. Recent contributions will appear in the main page.

Structure

You have 4 ways of finding articles.

The home page lists the most recent articles chronologically.
Categories groups articles by category.
Keywords groups articles by keyword.
Archives list a table of all articles chronologically.

How To Create File Patches

2025-05-24T18:23:52+00:00

Single File

This is how to build a patch file that you then apply on a target system to modify one of its files.

Get original copy

cp /pathtofile/myfile.conf /pathtofile/myfile.conf.orig

Edit the file manually

Using any editor, manually make changes to the file /pathtofile/myfile.conf as desired.

Capture the difference in a patch

diff -u /pathtofile/myfile.conf.orig /pathtofile/myfile.conf >myfile.patch

Try the patch

Undo the manual changes you made

patch -R -p0 <myfile.patch

Redo your changes

patch -p0 <myfile.patch

Recursive Directory

In this example capture all the changes we make to a tree of pelican-themes into a single patch file.

Duplicate

We start by duplicating the complete tree.

cp -r ${HOME}/pelican-themes ${HOME}/pelican-themes.orig

TIP

I have a tendency keep my orig copy and reuse it a lot as I modify things. To guard against inadvertantly changing something within the orig version without noticing and thereby undermining all subsequent diffs may make, I like to boiler plate the .orig files a bit by write protecting them. This is not necessary but it has served me well.

chmod -w --recursive pelican-themes.orig/

Create Patch File

Now we make all the changes we want within the pelican-themes directory. Once that is done we create the patch file incorporationg all changes.

cd ${HOME}/pelican-themes
diff -Naru ../pelican-themes.orig . > ../pelican-themes.patch

Note:

-N --new-file treat absent files as empty

-a --text treat all files as text

-r --recursive recursively compare subdirectories

-u -U --unified[=NUM] Output NUM lines of unified context (default 3)

Undo Changes

cd ${HOME}/pelican-themes
patch -Rs -p0 < ${HOME}/pelican-themes.patch

Note:

Remember that directories created by patch must be removed manually

-R --reverse Assume the patch was created with old and new files swapped

-s --silent be quiet unless error occurs

-pN Strip smallest filepath prefix containing N slashes. 0 means full path.

Apply Patch Changes

cd ${HOME}/pelican-themes
patch -s -p0 < ${HOME}/pelican-themes.patch

Set up a personal python package index

2025-05-24T18:23:52+00:00

Overview

This document describes setting up a private package index as a more convenient way to distribute python packages.

The need to use something like this grows as we add maintainers and packages to maintain.

Our python packages need to be compatile with the standard python package index PyPi.

We use a private package index until we are ready to make a package available to the general public, then we switch to PyPi.

This tool we are using keeps our packages compatible with PyPi for when we do make it available there.

devpi

It is a conforming package index system.

We will use it to serve our private package index.

Configuring the SW for devpi

This howto is derived from the following tutorial:

<https://devpi.net/docs/devpi/devpi/stable/+doc/quickstart-releaseprocess.html>_

We are working with python3. We want to setup up a virtual environment that conforms to our assumptions, and then install within that. We call the environment devpi_venv. We create a directory for our setup first.

mkdir ${HOME}/devpi_setup
cd ${HOME}/devpi_setup

We install the bare essentials.

python3 -m venv devpi_venv
source devpi_venv/bin/activate
python -m pip install -U pip
pip install wheel
pip install setuptools
pip install twine

restview is A Restructured Text format viewer I find usefull. (optional)

pip install restview

You invoke it and it keeps re-rendering your file as you modify it.

Like this:

restview README.rst

rst2pdf is convenient for generating pdf copies of .rst documuents.

pip install rst2pdf
rst2pdf doc/privatepypi.rst -o reformatted_docs/privatepypi.pdf

Set up devpi server on our laptop

Install devpi client and web server The non web server - devpi-server - is installed as a consequence.

pip install -U devpi-web devpi-client

Initialize an empty index (at /var/devpi-server by default) Note I had a permissions problem with the init one. So first I manually do this:

sudo mkdir  /var/devpi-server
sudo chown ubuntu:ubuntu /var/devpi-server

devpi-init

We want a config file for supervisor daemon to use. This will generate a bunch of config files under the current directory, the one we want included.

cd ${HOME}/devpi_setup
devpi-gen-config

This gives us the file gen-config/supervisor-devpi.conf to copy to /etc/supervisor/conf so that we can start up the server. I started by editing it to say start=False so that it would need to be started up manually. Then I copied it to the right place for it.

sudo cp gen-config/supervisor-devpi.conf /etc/supervisor/conf.d/devpi-server.conf
sudo supervisorctl update
sudo supervisorctl start devpi-server

Create a user, login as him and create the 'dev' index

devpi user -c pbernatchez password=foobar
devpi login pbernatchez --password=foobar
devpi index -c dev bases=root/pypi

Use our dev index

devpi use testuser/dev

Now we can make use of the private index.

We are using flit to publish to our index and it relies on the file : ~/.pypirc.

So we make an entry there for our index.

I gave it the name 'mypypi':

[distutils]
index-servers =
   mypypi
   testpypi

[mypypi]
repository = http://localhost:3141/pbernatchez/dev
username = pbernatchez

[testpypi]
repository = https://test.pypi.org/legacy/
username = pbernatchez

From here on, using flit, we can refer it as 'mypypi'.

deactivate
cd /home/ubuntu/allrepos/animbboard
source ${HOME}/venv_animbboard/bin/activate
flit build
flit publish --repository mypypi
pip uninstall  animbboard
pip install -i http://localhost:3141/pbernatchez/dev  animbboard

Set up a private package index

2025-05-24T18:23:52+00:00

Overview

At this writing our current practise is to generate versioned tarballs and to 'pip install' from those.

This describes setting up a private package index as a more convenient alternative to using tarballs directly.

Our python software needs to be kept compatible with the standard python package index for when we desire to offer it to the general public.

To ensure we are staying compatible with pypi, we need to run it through the process, but with a conforming private packaging index.

devpi to the rescue ('https://www.devpi.net/') .

It is a conforming package index system we can use to serve our private packages whithout releasing them to the public.

Configuring the SW for devpi

This information is derived from the following tutorial:

<https://devpi.net/docs/devpi/devpi/stable/+doc/quickstart-releaseprocess.html>_

We start by creating a virtual environment called "venv_devpi" by following the steps described in the document virtualenv.

Then we activate that environment and continue with the steps below.

Set up devpi server on our laptop

Install a devpi client and web server
pip install -U devpi-web devpi-client
Note:
The non-web server - devpi-server - is also installed as a side effect.
We must avoid needing sudo to access the index, so instead we change ownership from root to the logged in user. We also need to make sure supervisor runs our server as that user.

First manually do this:
sudo mkdir -p /var/devpi-server
sudo chown -R $(logname):$(logname) /var/devpi-server
ls -ld /var/devpi-server
Initialize an empty index (at /var/devpi-server by default)
devpi-init
Make a place to put our configuration data files:
mkdir -p ${HOME}/devpi_setup
The following will generate a bunch of config files, one of which we will need, under the current directory. Putting that stuff in ${HOME}/devpi_setup.
pushd . >/dev/null
cd ${HOME}/devpi_setup
devpi-gen-config
popd  >/dev/null
Note:
This gave us the file  ${HOME}/devpi_setup/gen-config/supervisor-devpi.conf
as a config file to start up our pypi server.  Start by editing
it manually to say autostart=False so that it will need to be
started up manually.
Append a line like "user = username" to the configuration so it launches as that user, the same user as above.
echo user = $(logname) >>${HOME}/devpi_setup/gen-config/supervisor-devpi.conf
Copy the config where where it needs to be, then start our server.
sudo cp ${HOME}/devpi_setup/gen-config/supervisor-devpi.conf /etc/supervisor/conf.d/supervisor-devpi.conf
sudo supervisorctl update
sudo supervisorctl start devpi-server
Create a user (within the server), login as that user and create the 'bzdev' index
devpi use http://localhost:3141
devpi user -c pbernatchez password=dummy
devpi login pbernatchez --password=dummy
devpi index -c bzdev bases=root/pypi
Use our bzdev index
devpi use pbernatchez/bzdev
Now we can make use of our private index.

We are using flit to publish to our index and it relies on the file : ~/.pypirc.

For pip I named it 'bzdevpi'. So we make an entry there for our index:
[distutils]
index-servers =
   bzdevpi
   testpypi

[bzdevpi]
repository = http://localhost:3141/pbernatchez/bzdev
username = pbernatchez

[testpypi]
repository = https://test.pypi.org/legacy/
username = pbernatchez
From here on, using flit,

To publish,

flit publish --repository bzdevpi

To install,

pip install -i http://localhost:3141/pbernatchez/bzdev foobar

Example:
deactivate
cd /home/ubuntu/allrepos/wait_ssh
source ${HOME}/venv_generic/bin/activate
flit build
flit publish --repository bzdevpi
pip uninstall wait_ssh
pip install -i http://localhost:3141/pbernatchez/bzdev wait_ssh

Set up a python virtual environment

2025-05-24T18:23:52+00:00

Make sure ubuntu system version is recent enough

lsb_release -a

Output (or higher)

Distributor ID:     Ubuntu

Description:        Ubuntu 24.04.3 LTS

Release:            24.04

Codename:           noble

python3 -V

Output

::: Python 3.12.3

Make a base for all our virtual environments

mkdir ${HOME}/.venv
# Now we can create all our virtual environments  under ${HOME}/.venv/

Make a Python Virtual Environment

# Here we call our first environment devpi
cd ${HOME}/.venv/
python3 -m venv devpi

OR using venvwrapper

mkvenv devpi

Once we have our environment created. We can install the elements we need to get started.

Activate It

source ${HOME}/.venv/devpi/bin/activate

Or with venvwrapper

venv devpi

install the basics

# install
python -m pip install -U pip
pip install wheel
pip install setuptools
pip install twine
pip install rst2pdf
pip install flit

# de-activate
deactivate

Saving prerequisites

Once your virtual environment is complete, it is nice to save the context. Then you can quicky restore your virtual environment from scratch if need be.

While Activated

pip freeze >requirements.txt

# It may be a good idea to keep such files under version control.

Recovering While Activated

pip install -r requirements.txt

Automatic activation

In many cases we want to activate a project whenever we log in. We can do that automatically by adding something like this to .bashrc and/or .profile

#
# Added for automatic vitual environment activation
#
if [ -f "${HOME}/.venv/devpi/bin/activate" ] ; then
    source ${HOME}/.venv/devpi/bin/activate
fi

OR with venvwrapper

#
# Added for automatic vitual environment activation
#
VENV_HOME=${HOME}/.venv
venv_wrapper=$(which venvwrapper.sh)
if [[ -n $venv_wrapper ]]; then
    source $venv_wrapper
    venv devpi
fi

python virtual environment

2025-05-24T18:23:52+00:00

Python Virtual Environment Setup

To have a good control over pre-requisite library modules for our software, we run in a python virtual environment.

That means that whenever you want to use or maintain the software you must first activate that virtual environment like this: (replace 'generic' with an existing project environment name)

source ${HOME}/venv_generic/bin/activate

Once active you can deactivate it like this:

deactivate

Installation

We install any non pip packages we rely on, if any, first. Then we install virtualenv. Then we create a virtual environment. Then we activate it.

Install virtualenv itself.

sudo apt update
sudo apt install virtualenv

Install a .rst to .pdf converter.

snap install rst2pdf

Create a virtual environment for the project

virtualenv --prompt venv_generic ${HOME}/venv_generic

Then activate the created environment

source ${HOME}/venv_generic/bin/activate

Now we install modules our project will need, first pip itself and the tools it needs.

python3 -m pip install -U pip
pip install wheel
pip install setuptools
pip install twine

We are using flit for building and installling our software.

pip install flit

Saving prerequisites

We keep our dependencies under version control, so each time we install more components we need to refresh our requirements file.

pip freeze >${HOME}/allrepos/generic/requirements.txt

Reinstalling

Later, when we are migrating to a different workstation, or for some reason need to restablish our project from scratch, we can install all our prerequisites in one shot instead of installing items one at a time like we did above.

pip install -r ${HOME}/allrepos/generic/requirements.txt

Automatic activation

In many cases we want to activate a project whenver we log in, so lets do that automatically.

Append this snippet to the end of our "${HOME}/.bashrc" file.

#
# Added for automatic vitual environment activation
#
if [ -f "${HOME}/venv_generic/bin/activate" ] ; then
    source ${HOME}/venv_generic/bin/activate
fi

Good ignoring keeps flit happy

Flit works nicely with git, but it is quite strict, so we must ignore all irrelevant files properly or flit will reject builds.

Below is a good start for a project ".gitignore" file:

*~
\#*\#
dist/*
pdf_docs/*
html_docs/*

Set Up A Wrapper For Venv Environments

2025-05-24T18:23:52+00:00

To maintain more than one python project at a time we leverage the the builtin python venv tool for creating and using virtual environments.

The venvwrapper package helps to keep the maintenance of multiple virtual environments easier. In short venv is enough, but venvwrapper makes it easier.

Installation

Install the venvwrapper package into your default system Python 3. That is, with no virtual environment active. This installs venvwrapper.sh so that it is available in PATH

sudo pip3 install --break-system-packages venvwrapper

Check that it is indeed available

which venvwrapper.sh

Set up automatic activation of venvwrapper

Add the code snippet below to one or both of these two files.

${HOME}/.bashrc
${HOME}/.profile

Code snippet:

VENV_HOME=${HOME}/.venv
venv_wrapper=$(which venvwrapper.sh)
if [[ -n ${venv_wrapper} ]]; then
    source ${venv_wrapper}
fi

Now Once you open a terminal window you have access to these commands

mkvenv devpi  # create and activate a new virtual environment
venv   devpi  # activate an existing virtual environment
rmvenv devpi  # remove one or more virtual environments
lsvenv        # list existing virtual environments

Metadata attributes in each article

2025-04-16T00:37:11+00:00

Pelican requires meta data like these

:lang: en
:date: 2025-04-16 00:37:11+00:00
:tags: metadata, article, pelican
:slug: articlemeta
:category: pelican
:authors: Pierre Bernatchez
:summary: Metadata in articles

Insert them below the initial heading of every article.

These ones should be identical in all translations of an article.

:date: 2025-04-16 00:37:11+00:00
:slug: sitehome
:authors: Nuno Yobidness.

These ones must be be translated into the different language versions of the article.

:lang: en
:tags: introduction
:category: pelican
:summary: Welcome to Site

These ones are optional.

Prevents the content from coming out under menus, pages, keywords and categories. It will be generated, but you will need a link somewhere to get to it.

use the same value in all languages.

:status: hidden

Overrides the default page footer copyright Value is language dependant.

:fcopyright: Copyright © 2026 Isaac Mejia—all rights reserved.

mypelican_static_sites git project

2025-04-16T00:37:11+00:00

Overview

This is a github project that uses a site generator called pelican to generate static websites.

At this writing this project maintains the content and generation for three seperate sites. Each site is rendered in 3 languages, english, french and spanish.

By convention we name each of these subdirectories using the domain name of the site. The scripts rely on this fact.

Currently Maintained Sites

www.bernatchez.net

Hosted in Bunny.net: www-bernatchez-net
www.ogopogo.biz

Hosted in Bunny.net: www-ogopogo-biz
blog.bernatchez.net

Hosted in Bunny.net: blog-bernatchez-net
docs.pelican.bernatchez.net

Hosted unpublished on local file system.

Web site generation

Generate a local version of a site so that you can browse and review it before publishing it.

cd ./blog.bernatchez.net
make html
xdg-open ./bucket/index.html
cd ..

Generate an online version of the site and publish it.

cd ./blog.bernatchez.net
# Make sure the deploy.bunny file actually runs an "nmx" command rather than just echoing it.
make pubhtml

# Manually Invoke the command printed as the last line by the above make
# This pushes everything out to CDN cache
npx --yes bunny-transfer@latest purge blog-bernatchez-net-zone

Warning

Once you have invoked "make pubhtml", your "local site" content will no longer be appropriate for local viewing. If you wish to browse both local and online versions interchangebly. You need to repeat the "make html" once you have published thereby leaving the local files configured for local viewing.

Web Site Maintenance

Scope

The git project is organized to have 2 scopes for site source
content.

*Global source scope*

   The .rst files contained in subdirectories of the main project directory.
   These files can be sourced by any of our websites.

*Local source scope*

   The .rst files contained within subdirectories under a given site subdirectory.
   These files can only be sourced by the given website.

A given site's "content" subdirectoy contains subdirectories whose
names match either global or local scope subdirectories. That
identifies what will be included in the site.

What directory names appear in the "content" directory determines
what is included in the generated site.

The make file handles populating such directories with with soft
links to the .rst source files in their corresponding local or
global scope directory.

Insofar as the repository is concerned you only "git add" .rst
files which are in global or local scope directories.  The
subdirectories under content/ will only contain "placeholder.txt"
within git to make sure their subdirectories are created upon
clone.

pdf source

All our sites also contain .pdf versions of their pages.  To
produce those pdf files, each source directory also contains two
executable script files: **article2pdf**, and **qarticle2pdf**.
The latter is just a less verbose version.  Whenever you modify or
add content in a source directory, remember to re-regenerate the
.pdf files accordingly.

Generally, you modify your content, and then invoke "qarticle2pdf"
to make sure your pdfs are up to date.

If you have created a mew source directory you can generate those two scripts
in it by invoking the command "genarticle2pdf -q" inside the new directdory.

github maintenance

When you clone the github project to a local directory, you end up
with a main directory which contains web site subdirectories, each
of those is an independant web site generation directory.

The project main directory contains various *Global source scope*
site subdirectories (E.G. ./examples, ./artwork, ./travel,
etc...). Each of these contain .rst files that can serve as source
for site content generation. All under git revision control.

This *Global source scope* content can optionally be used as source
for any of the web sites.

Each web site subdirectory can also contain its own subdirectories
containing site specific *Local source scope* .rst files
(E.G. ./blog.bernatchez.net/pages/) intended only for the given
site.

To add any one of these *local or global scope* content directories
to a given web site, you need to create a directory of the same
name under the given site's content subdirectory.  You must also
add a "placeholder.txt" file and put it under revision control
(e.g. git add placeholder.txt) to enssure that new directory will
be created upon use of "git clone".

For example we did this to add ./examples to the ./blog.bernatchez.net web site:

mkdir ./blog.bernatchez.net/content/examples/
cp ./blog.bernatchez.net/content/pages/placeholder.txt ./blog.bernatchez.net/content/examples/
git add ./blog.bernatchez.net/content/examples/placeholder.txt

You also need to modify the project .gitignore file to avoid adding
the generated soft links under content/examples into the git
repository.  Those links are regenerated every make.

We added the lines below to .gitignore:

blog.bernatchez.net/content/examples/
blog.bernatchez.net/content/examples/*

Repository

The original central copy of this project's repository is:

git@github.com:pierrebernatchez/mypelican_static_sites.git

Article Starting Point

2024-12-06T20:05:03+00:00

Sample RST content to start from and modify for your article.

Main Header for your article
#############################################

:lang: en
:category: a valid category
:date: 2025-10-11 20:03:36+00:00
:tags: article, template
:slug: unique-article-name
:authors: Pierre Bernatchez
:summary: One line Summary of your article

.. |copy| unicode:: 0xA9 .. copyright sign

.. |---| unicode:: U+02014 .. em dash
   :trim:

.. footer:: Copyright |copy| 2025 Pierre Bernatchez |---| all rights reserved.


Start here

Modify the main header to something suitable for your artricle.

Modify category to one appropriate for your article.

Modify date. You can use command line command "date -u --rfc-3339=seconds" to get a correctly formatted date string.

Modify tags to relevant keywords for your article.

Modify slug to be the unique name for your article. We use that as the basis for the file name of the .rst file. Like this slugname-en.rst, slugname-es.rst, slugname-fr.rst are the 3 language file names for the article with the slug: slugname.

Modify authors to your own name.

Modify summary to something appropriate to your article.

Modify the name in the footer line to yours also.

Write your article, using RST markup beginning at start here

Note that there there are two convenience python scripts that can generate something to start from for a new article.

Generate an article starting point with no image

newarticle -h

usage: newarticle [-h] [-a AUTHOR] [-l {en,fr,es,all}] [-d DUP] [-r]
                  articlename

Generate a skeleton article file

positional arguments:
  articlename           article name without the "-en.rst")

options:
  -h, --help            show this help message and exit
  -a AUTHOR, --author AUTHOR
                        Author for copyright and for authors (default "Pierre
                        Bernatchez)"
  -l {en,fr,es,all}, --lang {en,fr,es,all}
                        language of the new article (default: all)
  -d DUP, --dup DUP     Existing article name to duplicate category and tags
                        (default None)
  -r, --recipe          Treat this as a recipe. (Othewise generic)

Generate an article starting point with an image

newshot -h

Output

usage: newshot [-h] [-a AUTHOR] [-l {en,fr,es,all}] [-d DUP] [-j] [-r]
               articlename

Generate a skeleton article file which has a srcreenshot

positional arguments:
  articlename           article name without the "-en.rst")

options:
  -h, --help            show this help message and exit
  -a AUTHOR, --author AUTHOR
                        Author for copyright and for authors (default "Pierre
                        Bernatchez)"
  -l {en,fr,es,all}, --lang {en,fr,es,all}
                        language of the new article (default: all)
  -d DUP, --dup DUP     Existing article name to duplicate category and tags
                        (default None)
  -j, --jpg             Reference image as a .jpg rather than a .png a
                        (default: False)
  -r, --recipe          Treat this as a recipe. (Othewise generic)

Theme «Lightweight» for pelican

2024-12-06T20:02:44+00:00

Description

:Created on: 14 February 2011
:Technologies used: xHTML5, CSS 1-3, polices TTF
:Colors Used: Cold Tones (grey/blue)
:Extensive design: Yes
:Tested Under: Mozilla Firefox 4.0b10, Chromium 9.0.597.83, ELinks 0.12pre5
:Language: English
:Details: See Screenshot and source

This theme is derived From the french language lightweight theme. It has been altered so that the home page lists only a few of the most recent articles. It has been translated to english.

Screenshot

Pelican Web Site Generator Configuration

2024-12-02T17:30:00-05:00

Pelican is a static web site generator. It is the tool we are using to maintain our static sites.

This documet assumes we are using venvwrapper [1].

Install Pelican

Do it within our python virtual environment. We named our environment statsites.

Activate it, and install Pelican

venv statsites
pip install pelican

Themes

In each of our pelicanconf.py configurations we select a theme for the given site. To get a collection of themes to choose from, we cloned as follows:

git clone --recursive https://github.com/getpelican/pelican-themes ${HOME}/pelican-themes

Site Theme Note

In our own sites we have made a few adjustments to the lightweight theme to suit our purpose. We maintain this derived theme and our web content under our git version control repository. Our pelicanconf-en.py configuration file has this reference.

THEME = u"/home/ubuntu/allrepos/mystatic_sites/derived-themes/lightweight-single-home-en"

Your site's theme will be for you to choose and/or modify.

Initialize Skeletal Site File Sytem

Use 'pelican-quickstart' to generate initial static website content using pelican.

pelican-quickstart creates the a skeletal site generation file system beneath the current empty directory.

Afterwards you create .rst files in content/anyname directories as blog articles. Ccreate .rst files in content/pages as blog pages.

Compilation

Generate the web site files once we have all our .rst source files. For this we only need to use the Makefile. The following will compile and emit all the web site content under output/ using pelican.

make html

Your can review your results by invoking the output/index.html file.

[1]	We are using the package venvwrapper to simplify virtual environment management. That fact is assumed in this document. If you are not using it, you need to replace lines here such as: "venv statsites", with lines such as "source ${HOME}/.venv/statsites/bin/activate".

Project Source Organization

2024-12-02T17:30:00-05:00

At this writing we are maintaining pelican generated static websites, one for blog.bernatchez.net and one for www.ogopogo.biz.

We use our script "compile_rst" to add a few generated .rst files to the source site before using pelican to generate the site from source.

We can generate a list of links to the files in a subdirectory.

Accomplished like this in the Makefile.

$(COMPILE_RST) -p '*.pdf' -s sitepdfs -o pdfs_list -i

That would generate a link for each .pdf file in sitepdfs/ and emit the result to the file pdfs_list.rst

Such a file is intended to be included within one or more of our manually produced .rst pages with a line like:

.. include:: ../../pdfs_list.rst

That would include our generated link list in that page.

We can also generate music album like pages with links to the files in a compilation subdirectory.

Accomplished like this in the Makefile.

$(COMPILE_RST) -p '*.mp3' -s compilations -o album -a

This would generate - possibly - several album_N.rst files in the pages/ subdirectory, where N is a sequence number. You will get as many pages as there are albums referenced in the m3 files in the compilations directory.

Invocations of compile_rst must take place every time the make html target is requested.

For example, the bernatchez_staticweb Makefile contains this

html:

    $(COMPILE_RST) -p '*.mp3' -s compilations -o album -a
    $(COMPILE_RST) -p '*.tar.gz' -s tarballs -o tarballs_list -i
    $(COMPILE_RST) -p '*.pdf' -s sitepdfs -o pdfs_list -i
    $(PELICAN) $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS)

So that content/pages/album_N.rst files and tarballs_list.rst, pdfs_list.rst are all regenerated prior to invoking pelican to generate the site.

In short

Files tarballs/*.tar.gz , sitepfds/*.pdf, and compilations/*.mp3 as well as all the .rst files under the content subdirectory determine what goes into our website.

At this writing the content is only proof of concept data.

Pelican Theme Screenshots

2024-12-02T17:30:00-05:00

Decreasing order of preference

lightweight

THEME = "/home/ubuntu/pelican-themes/lightweight"

sneakyidea

THEME = "/home/ubuntu/pelican-themes/sneakyidea"

basic

THEME = "/home/ubuntu/pelican-themes/basic"

notmyidea-cms

THEME = "/home/ubuntu/pelican-themes/notmyidea-cms"

notebook

THEME = "/home/ubuntu/pelican-themes/notebook"

cebong

THEME = "/home/ubuntu/pelican-themes/cebong"

relapse

THEME = "/home/ubuntu/pelican-themes/relapse"

bold

THEME = "/home/ubuntu/pelican-themes/bold"

bootstrap2-dark

THEME = "/home/ubuntu/pelican-themes/bootstrap2-dark"

franticworld

THEME = "/home/ubuntu/pelican-themes/franticworld"

Theme Note

2024-12-02T17:30:00-05:00

Notes regarding selecting and tweaking pelican themes used with our sites.

To be able to use/tweak pelican themes for my pelican projects I cloned the full collection of pelican themes to my local machine.

git clone --recursive https://github.com/getpelican/pelican-themes /home/ubuntu/pelican-themes

I then replicated the tree to use as a basis for getting a diff to identify any changes that I made during the course of tweaking themes I use.

cp -r ${HOME}/pelican-themes ${HOME}/pelican-themes.orig
chmod -w --recursive ${HOME}/pelican-themes.orig  # To make my orig write protected for reliable diffs later.

Do this once in a while as we tweak themes we are using, so we can keep a record of our tweaks.

cd ${HOME}/pelican-themes
diff -Naru ../pelican-themes.orig . > ../pelican-themes.patch

Note:

-N --new-file treat absent files as empty

-a --text treat all files as text

-r --recursive recursively compare subdirectories

-u -U --unified[=NUM] Output NUM lines of unified context (default 3)

Pelican Themes

2024-11-18T20:41:00-05:00

sneakyidea

THEME = "/home/ubuntu/pelican-themes/sneakyidea"

lightweight

THEME = "/home/ubuntu/pelican-themes/lightweight"

basic

THEME = "/home/ubuntu/pelican-themes/basic"

notmyidea-cms

THEME = "/home/ubuntu/pelican-themes/notmyidea-cms"

bold

THEME = "/home/ubuntu/pelican-themes/bold"

Github Clone Note

2015-03-19T11:47:31-04:00

If you have just cloned the "mypelican_static_sites" repostitory, you need to take a few steps before generating the sites.

pre-requisites

Our builds for the sites maintained here rely on the "flitprojects" project that is also under our github account's revision control. That project relies on python virtual environments. So we are assuming that an adequate virtual environment is set up, and that we have done flit build, and flit install into it of the "flitprojects/articleware" package.

Newly cloned "mypelican_static_sites" setup steps

Install scripts to generate the pdf versions of all the articles. These scripts are genereated so they are not kept under version control. We use a bash script to identify the list of site subdirectories and generate our scripts within each of those.

allputs.sh
# this generates a pair of scripts in each subdirectory
# that contains article .rst files.

Once the scripts have been generated. We need to get all the .pdf files generated. We do that by going to any of the site subdirecgtories and using make to generate the .pdf files.

cd www.bernatchez.net
make pdfs

Generate your local versions of your sites so that you can double check that they are good to go.

cd www.bernatchez.net
make html
cd ..

cd blog.bernatchez.net
make html
cd ..

cd www.ogopogo.biz
make html
cd ..

cd docs.pelican.bernatchez.net
make html
cd ..

Generate the publishable versions of your sites and publish them.

cd www.bernatchez.net
make pubhtml
cd ..

cd blog.bernatchez.net
make pubhtml
cd ..

cd www.ogopogo.biz
make pubhtml
cd ..

# Only use the filesystem version of this one, so don't generate.
# We do not maintain the site with the bunny CDS.
cd docs.pelican.bernatchez.net site
echo 'We do not maintain the site "docs.pelican.bernatchez.net" with the bunny CDS.'
cd ..

Make with "pubhtml" yields online locations within many of the links inside the content. This is incompatible with the make "html" generated content whose links must all be file system relative. This means that the content on the local file system is no longer valid immediately after generating "pubhtml" content. So we have to re-run make "html" once we have published the content to revert the local content to what is should be.

cd www.bernatchez.net
make html
cd ..

cd blog.bernatchez.net
make html
cd ..

cd www.ogopogo.biz
make html
cd ..

Troubleshooting Site Generation

2015-03-19T11:47:31-04:00

I intend to keep adding to this note as further issues crop up and workarounds are discovered.

1- I found that when we use the same slug for different language versions of the same article.

pelican does a nice job of picking out the current default language's version for the site. When no version exists which matches the current default language, then pelican emits warnings and/or errors regarding the other language versions.

The work around is to always make sure you have all the language versions you are supporting, or just a single one. When that is the case it seems to behave adequately.

It seems sensible to translate attribute values too, other than slug of course.

Web Site Articles Rendered In PDF

2015-03-11T12:47:00-04:00

Site Articles Re-Rendered In PDF

Site articles in PDF format.