documentation to PDF

[gurucubano]

Hello,
I'm missing somehow a Makefile or script to make from the Marldown files below documentation/docs/ something which I could deliver to customers, for example in PDF.
How they're supposed to be used?
Thanks,
Matthias

[gurucubano]

As a workaound I run:

pandoc index.md install.md setup.md test.md uninstall.md tde.md -o pg_tde-documentation-docs.pdf

[nastena1606]

Hi there! We have created the way to build PDF docs for pg_tde. Please check it out here: https://percona-lab.github.io/pg_tde/main/contribute.html#build-pdf-file

[gurucubano]

I have had todo (I'm on MacOS):

brew install mkdocs
...
==> Installing mkdocs
==> Pouring mkdocs--1.6.0_1.arm64_sonoma.bottle.tar.gz
🍺  /opt/homebrew/Cellar/mkdocs/1.6.0_1: 472 files, 8.8MB
==> Running `brew cleanup mkdocs`...

cd pg_tde
git pull
...
cd documentation
ls
_resource		mkdocs-pdf.yml		requirements.txt
docs			mkdocs.yml		snippets
ls -l mkdocs-pdf.yml
-rw-r--r--  1 apitzm  32873736  397 15 Mai 13:49 mkdocs-pdf.yml

export ENABLED_GIT_REVISION_DATE=false
$ ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml
Error: MkDocs encountered an error parsing the configuration file: while constructing a Python object
cannot find module 'material.extensions.emoji' (No module named 'material')
  in "mkdocs.yml", line 98, column 20

What else do I miss?

[nastena1606]

Please check if you have mkdocs-material-extensions installed. If not, please install it with pip install mkdocs-material-extensions

[gurucubano]

I couldn't get pip to work on my Mac, so I went to my Linux server and did:

$ cd postgresql-16.2/contrib/pg_tde/
$ git pull
(ok)
$ cd documentation/
$ pip install mkdocs
(ok)
$ pip install material
(ok)
$ pip install mkdocs-material-extensions
(ok)
$ export PATH=$PATH:/home/sisis/.local/bin
$ export ENABLED_GIT_REVISION_DATE=false
$ ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml
Error: MkDocs encountered an error parsing the configuration file: while constructing a Python object
cannot find module 'material.extensions.emoji' (No module named 'material.extensions')
  in "mkdocs.yml", line 98, column 20

[ImTheKai]

Ensure that you have the materialx module installed. You can install it using the following command:

pip install mkdocs-material

Confirm that the materialx module is successfully installed by running the following command:

pip show mkdocs-material

If this doesn't work either we would need to check if you have multiple python versions installed and if the version used for the build is a different one.

[gurucubano]

The word distributionis not fully clear. The Linux distribution is:

$ cat /etc/os-release
NAME="SLES"
VERSION="15-SP5"
VERSION_ID="15.5"
PRETTY_NAME="SUSE Linux Enterprise Server 15 SP5"
ID="sles"
ID_LIKE="suse"
ANSI_COLOR="0;32"
CPE_NAME="cpe:/o:suse:sles:15:sp5"
DOCUMENTATION_URL="https://documentation.suse.com/"

About pipit is and there are 83 python* RPMs installed:

$ which pip
/usr/bin/pip
$ rpm -q -f /usr/bin/pip
python3-pip-20.0.2-150400.20.1.noarch
$ rpm -qa | grep python | wc -l
83

Do you want me to send the list of rpm -qa | grep python?

[ImTheKai]

No that's sufficient for now. I first of all would actually need a SLES, which complicates the situation already a lot, as those type of "build/dev" packages are not part of the main distro, that's not the purpose of SLES. I would need to check what's included or what's not. To build everything on Ubuntu or Debian for example, would make your life much easier in that case.

[gurucubano]

Kai, I'm working for a company which produces a Library Management System (LMS SunRise) for big University libraries or bigger public ones. The system runs on SuSE Linux SLES 15 and on top of the DBS PostgreSQL 15.1 and now also 16.2. This only as background of my intention getting pg_tde investigated and later included when it is ready for production use. The LMS is deployed to 100++ customers. This only as background.

We also use Red Hat 8.x for internal things and I did an attempt to make the doc in PDF there. I installed as root:

# pip3 install mkdocs
# pip3 install material
# pip3 install mkdocs-material-extensions

and gave it a try:

$ export ENABLED_GIT_REVISION_DATE=false
$ export ENABLE_PDF_EXPORT=1
$ mkdocs build -f mkdocs-pdf.yml
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 7, in <module>
    from mkdocs.__main__ import cli
ModuleNotFoundError: No module named 'mkdocs'

For sure it's missing some pointer to the modules. I've to say I'm unused to Python (my background is UNIX and C).

[gurucubano]

I had to fix permissions below /usr/local/lib/python3.6/ (setting 0755 for dirs and 0644 for files, read andsearch were denied for normal user) which now gives:

$ mkdocs --version
mkdocs, version 1.3.1 from /usr/local/lib/python3.6/site-packages/mkdocs (Python 3.6)

$ mkdocs build -f mkdocs-pdf.yml
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 11, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.6/site-packages/click/core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.6/site-packages/click/core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.6/site-packages/click/core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.6/site-packages/click/core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.6/site-packages/click/core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.6/site-packages/mkdocs/__main__.py", line 191, in build_command
    from mkdocs.commands import build
  File "/usr/local/lib/python3.6/site-packages/mkdocs/commands/build.py", line 6, in <module>
    from jinja2.exceptions import TemplateNotFound
  File "/usr/local/lib/python3.6/site-packages/jinja2/__init__.py", line 8, in <module>
    from .environment import Environment as Environment
  File "/usr/local/lib/python3.6/site-packages/jinja2/environment.py", line 15, in <module>
    from markupsafe import Markup
ModuleNotFoundError: No module named 'markupsafe'

[nastena1606]

Matthias, MkDocs-material theme requires Python version => 3.8. Could you please try upgrading it, and also please try installing all required packages by running pip3 install -f requirements.txt.

[gurucubano]

$ python3 --version
Python 3.9.18

Und als root:

# pip3 install mkdocs -f requirements.txt
# pip3 install material -f requirements.txt
# pip3 install mkdocs-material-extensions -f requirements.txt
# find /usr/local/lib/python3.6 -type f -exec chmod 0644 {} \;
# find /usr/local/lib/python3.6 -type d -exec chmod 0755 {} \;

Der Fehler bleibt.