biisan 0.8.2

Description:

biisan 0.8.2

biisan

biisan is a static site generator that can write documents in reStructuredText.
Feature

Convert the structure of reStructuredText to the structure of object, and output to html with jinja2 template for each Directives of reStructuredText
The default template is attached for the directives supported by biisan, but the template to be used can be replaced if the search destination is set in the configuration
The conversion processor from directive to object can also replace any processor by setting
The processing of the directive which is not supported is also possible by the same mechanism as replacement.
Easy definition of new directives
The process of converting the structure of reStructuredText to an object is performed in parallel in multiprocessing

quick start
Installation
It can be installed with pip. Since dependent libraries are also installed at the same time, you may want to create and install a virtual environment using venv if you want to be able to erase them cleanly.
$ pip install biisan

Initialize
Generate the basic structure of biisan and configuration file. There is a folder called biisan_data under the folder you have run.
Answer blog title, base URL, language code as it is asked. You can change it later in the configuration file.
$ python -m biisan.main
? What's your blog title blog title
? input your blog base url. like https://www.tsuyukimakoto.com http:localhost
? input your blog language like ja en

Always set environment variable BIISAN_SETTINGS_MODULE to biisan_local_settings like bellow.

$ export BIISAN_SETTINGS_MODULE=biisan_local_settings


Finally, the environment variables required whenever using biisan are output. It is an environment variable that is always required when using biisan.
It is a setting framework setting of glueplate.
First Entry
Let's check the contents of the generated folder.
$ cd biisan_data
$ tree
.
├── data
│ ├── biisan_local_settings.py
│ ├── blog
│ ├── extra
│ │ └── about.rst
│ └── templates
└── out

Inside the biisan_data folder there are two folders, data and out.


data


biisan_local_settings.py
setting file. It has been added to or overwritten in the Original file settings settings.


blog
Put the reStructuredText file in this. It is good to make a folder so that it is easy to organize. The folder structure in the blog folder has nothing to do with the path of the output URL.


extra
Put the file if you want to create a separate page from the date based entry. about is set by default.
When newly added, add the definition of GLUE_PLATE_PLUS_BEFORE_extra to the setting file (data/biisan_local_settings.py).
For example, if you put the file imusing.rst, define GLUE_PLATE_PLUS_BEFORE_extra in data/biisan_local_settings.py as follows.
# Omitted

settings = _(
# 省略
multiprocess = 8,
GLUE_PLATE_PLUS_BEFORE_extra = [
'imusing',
],
)

This is how glueplate works, ['imusing' before the extra setting in the original file settings file ',] Is added.
See also Actual setting.


templates
Put the template you want to overwrite. Like GLUE_PLATE_PLUS_BEFORE_extra, GLUE_PLATE_PLUS_BEFORE_template_dirs is defined in the configuration file, so first we will start looking for template files in this folder.




out
Html is output statically in this folder.



This is the first entry
Let's save as my_first_entry.rst in data/blog as follows. The file name may be anything before the file extension, as long as the extension is .rst.
Is the first entry
=========================================================

:slug: my_first_biisan_entry
:date: 2019-05-05 13:00
:author: Your name

Hello! world!

Build
The operation is done in the data directory (in biisan_data/data).
$ python -m biisan.generate

If you get an error like the following, it is because you have not set the environment variable displayed at the time of initialization.
Traceback (most recent call last):
(Omitted)
KeyError: 'BIISAN_SETTINGS_MODULE'

If you have not set the environment variable, try setting again and executing the command again.
$ export BIISAN_SETTINGS_MODULE=biisan_local_settings
$ python -m biisan.generate

If you get the following error, the folder where you are executing the command is wrong. Let's execute it in biisan_data/data.
Traceback (most recent call last):
(Omitted)
ModuleNotFoundError: No module named 'biisan_local_settings'

If it works, the output is as follows, so let's open it in a browser.
$ python -m biisan.generate
BIISAN 0.3.0
INFO:__main__:Write:(omitted)/biisan_data/out/blog/2019/05/05/my_first_biisan_entry/index.html
INFO:__main__:Write:(omitted)/biisan_data/out/about/index.html

The URL is composed of date and slug described in the entry. At this point, the data folder and the out folder are as follows.
.
├── data
│ ├── __pycache__
│ │ └── biisan_local_settings.cpython-37.pyc
│ ├── biisan_local_settings.py
│ ├── blog
│ │ └── my_first_entry.rst
│ ├── extra
│ │ └── about.rst
│ └── templates
└── out
├── about
│ └── index.html
├── api
│ ├── feed
│ │ └── index.xml
│ └── google_sitemaps
│ └── index.xml
├── blog
│ ├── 2019
│ │ └── 05
│ │ ├── 05
│ │ │ └── my_first_biisan_entry
│ │ │ └── index.html
│ │ └── index.html
│ └── index.html
└── index.html

Although the file name is index.html, it is assumed that it can be omitted by specifying the directory index of the Web server.
For example, https://www.tsuyukimakoto.com/about/ should be set to return index.html if the file name is omitted.
The entry path is created based on slug and date described in the entry rst file.
:slug: my_first_biisan_entry
:date: 2019-05-05 13:00

template
A template is provided for each directive. Put templates in the templates folder if you want to change the style etc.
Default template and real project template.
Deploy
Deploy the contents of out to an appropriate server. Don't forget to specify the directory index.