From d1a2323156c01c7fb70af2024c338cdcdda875d3 Mon Sep 17 00:00:00 2001 From: Erik Huelsmann Date: Wed, 25 Dec 2019 13:26:39 +0100 Subject: [PATCH] Improve Markdown rendering [skip ci] --- doc/database/README.md | 70 ++++++++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 27 deletions(-) diff --git a/doc/database/README.md b/doc/database/README.md index cf3af39eca..4c846ef9fb 100644 --- a/doc/database/README.md +++ b/doc/database/README.md @@ -1,21 +1,30 @@ # ledgersmb-database-doc + Database documentation to assist LedgerSMB users and developers -######Copyright (c) 2006 - 2017 LedgerSMB Project +```plain +Copyright (c) 2006 - 2017 LedgerSMB Project +``` + + +# How to generate doc +## Scripted -============================ -How to generate doc -============================ -You will need at least postgresql_autodoc and graphviz installed on your system. +You will need at least postgresql_autodoc and graphviz installed +on your system. -The script found here will automatically build the docs and images, outputing them into /tmp/LedgerSMB-doc -- `utils/devel/regen_db_docs.sh` +The script found here will automatically build the docs and images, +outputing them into /tmp/LedgerSMB-doc: + +```bash + $ utils/devel/regen_db_docs.sh` +``` regen_db_docs.sh takes 2 arguments -- --release : only for use during the official release process. -- --statistics : generates table statistics using the pgstattuple extension +- `--release`: only for use during the official release process. +- `--statistics`: generates table statistics using the pgstattuple extension regen_db_docs.sh will use these environment variables - PGHOST @@ -24,35 +33,42 @@ regen_db_docs.sh will use these environment variables - PGDATABASE - PGPASSWORD -It use a password from $PGPASSWORD, ~/.pgpass, or fallback to asking the user for a password. +It use a password from $PGPASSWORD, ~/.pgpass, or fallback to asking the +user for a password. + +Viewing the .svg or .svg.html versions of the images will likely provide +the best user experience -Viewing the .svg or .svg.html versions of the images will likely provide the best user experience +## Manually -============================ Alternatively you can generate the documentation manually with - PostgreSQL Autodoc - - https://github.com/cbbrowne/autodoc + * PostgreSQL Autodoc - https://github.com/cbbrowne/autodoc postgresql_autodoc -d -u postgres -f ledgersmb - GraphViz - - http://graphviz.org/ +* GraphViz - http://graphviz.org/ - The ledgersmb.dot file from PostgreSQL Autodoc is a text output meant to - be processed by GraphViz (or a compatible program), to make a image of all the database tables in LedgerSMB. +The ledgersmb.dot file from PostgreSQL Autodoc is a text output meant to +be processed by GraphViz (or a compatible program), to make a image of +all the database tables in LedgerSMB. + +Use the dot utility from GraphViz, to export a SVG image (Scalable Vector +Graphics) - Use the dot utility from GraphViz, to export a SVG image (Scalable Vector Graphics) - dot -Tsvg .dot -o .svg - - You can open .svg in many image viewers, or your web browser and zoom in our out on the image. - - Use the dot utility from GraphViz, to export a PDF. NOTE: the PDF has a large number of elements, and will be slow to load, and may have limited zoom capabilities in some viewers - + +You can open .svg in many image viewers, or your web browser +and zoom in our out on the image. + +Use the dot utility from GraphViz, to export a PDF. NOTE: the PDF has a +large number of elements, and will be slow to load, and may have limited +zoom capabilities in some viewers + dot -Tpdf .dot -o .pdf - - Use the dot utility from GraphViz, to export a PNG image: NOTE: This is a large image, and while readable, the resolution is not great. + +Use the dot utility from GraphViz, to export a PNG image: NOTE: This is +a large image, and while readable, the resolution is not great. dot -Tpng .dot -o .png