Documenting PostgreSQL Database¶
Please note that this article will cover only the basic usage of the tools. For detailed information on the features and customizing output refer to each component’s docs.
You will need to install some prerequisites. If you are running Foliant natively, follow the guide below. If you are working with our Full Docker image, you don’t need to do anything, you can skip to the next stage.
First, you will need Foliant, of course. If you don’t have it yet, please, refer to the installation guide.
Install PostgreSQL and its Python connector.
$ pip3 install psycopg2-binary
Install DBDoc and PlantUML preprocessors, and the Slate backend:
$ pip3 install foliantcontrib.dbdoc foliantcontrib.slate, foliantcontrib.plantuml
Finally, Install PlantUML, we will need it to draw the database scheme.
Let’s create a Foliant project for our experiments.
cd to the directory where you want your project created and run the
$ cd ~/foliant_projects $ foliant init Enter the project name: Database Docs Generating project... Done ──────────────────── Project "Database Docs" created in database-docs $ cd database-docs
The other option is to clone the Foliant Project template repository:
$ cd ~/foliant_projects $ mkdir database-docs $ git clone https://github.com/foliant-docs/foliant_project_template.git database-docs Cloning into 'database-docs'... remote: Enumerating objects: 11, done. remote: Counting objects: 100% (11/11), done. remote: Compressing objects: 100% (7/7), done. remote: Total 11 (delta 1), reused 11 (delta 1), pack-reused 0 Unpacking objects: 100% (11/11), done. $ cd database-docs
Setting up project¶
Now it’s time to set up our config. Open
foliant.yml and add the following lines:
title: Database Docs chapters: - index.md +preprocessors: + - dbdoc: + dbms: pgsql + host: localhost + port: 5432 + dbname: posgres + user: posgres + password: posgres + - plantuml +
Make sure to use proper credentials for your PostgreSQL database. If you are running Foliant from docker, you can use
host: host.docker.internal to access
localhost from docker.
Note: if plantuml is not available under
$ plantumlin your system, you will also need to specify path to platnum.jar in preprocessor settings like this:
- plantuml: plantuml_path: /usr/bin/plantuml.jar
Finally, we need to point Foliant the place in the Markdown source files where the generated documentation should be inserted. Since we already have an
index.md chapter created for us by
init command, let’s put it in there. Open
src/index.md and make it look like this:
# Welcome to Database Docs -Your content goes here. +<dbdoc></dbdoc> +
All preparations done, let’s build our site:
$ foliant make site -w slate Parsing config... Done Applying preprocessor dbdoc... Done Applying preprocessor plantuml... Done Applying preprocessor flatten... Done Applying preprocessor _unescape... Done Making site... Done ... ──────────────────── Result: Database_Docs-2020-06-03.slate/
If you are using Docker, the command is:
$ docker-compose run --rm foliant make site -w slate
Database_Docs-2020-06-03.slate/index.html and look what you’ve got:
That looks good enough, but you may want to tweak the appearance of your site. You can edit the Jinja-template to change the way DBDoc generates markdown out of your schema. The default template can be found here. Edit it and save in your project dir, then specify in the
doc_template parameter. If you want to change the looks of your site, please, refer for instructions in Slate backend documentation.