[#441] Documentation framework

CMakeLists.txt

@@ -32,6 +32,8 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 message(STATUS "pgagroal ${VERSION_STRING}")
 
+set(generation TRUE)
+
 include(CheckCCompilerFlag)
 include(CheckCSourceCompiles)
 include(CheckLinkerFlag)
@@ -87,6 +89,21 @@ else ()
   message(FATAL_ERROR "cJSON needed")
 endif()
 
+find_package(Pandoc)
+if (PANDOC_FOUND)
+  message(STATUS "pandoc found")
+else ()
+  set(generation FALSE)
+  message(STATUS "pandoc needed. The generation process will be skipped.")
+endif()
+
+find_package(Pdflatex)
+if (PDFLATEX_FOUND)
+  message(STATUS "pdflatex found")
+else ()
+  set(generation FALSE)
+  message(STATUS "pdflatex needed. The generation process will be skipped.")
+endif()
 
 if (${CMAKE_SYSTEM_NAME} STREQUAL "Linux")
   find_package(Libatomic)

README.md

@@ -1,6 +1,6 @@
 # pgagroal
 
-`pgagroal` is a high-performance protocol-native connection pool for [PostgreSQL](https://www.postgresql.org).
+[**pgagroal**](https://github.com/agroal/pgagroal) is a high-performance protocol-native connection pool for [PostgreSQL](https://www.postgresql.org).
 
 Pronounced: p-g-a-gro-al, named after [A](https://www.visitportugal.com/en/content/praia-fluvial-do-agroal)[gro](https://www.google.com/maps/place/Agroal,+Portugal/@39.6775431,-8.4486056,14z/)[al](https://www.infatima.pt/en/nearby/sun-sea/fluvial-beaches/agroal/) in Portugal.
 
@@ -23,15 +23,15 @@ Pronounced: p-g-a-gro-al, named after [A](https://www.visitportugal.com/en/conte
 * Daemon mode
 * User vault
 
-See [Getting Started](./doc/GETTING_STARTED.md) on how to get started with `pgagroal`.
+See [Getting Started](./doc/GETTING_STARTED.md) on how to get started with [**pgagroal**](https://github.com/agroal/pgagroal).
 
-See [Configuration](./doc/CONFIGURATION.md) on how to configure `pgagroal`.
+See [Configuration](./doc/CONFIGURATION.md) on how to configure [**pgagroal**](https://github.com/agroal/pgagroal).
 
 See [Performance](./doc/PERFORMANCE.md) for a performance run.
 
 ## Overview
 
-`pgagroal` makes use of
+[**pgagroal**](https://github.com/agroal/pgagroal) makes use of
 
 * Process model
 * Shared memory model across processes
@@ -40,10 +40,10 @@ See [Performance](./doc/PERFORMANCE.md) for a performance run.
 * The [PostgreSQL](https://www.postgresql.org) native protocol
   [v3](https://www.postgresql.org/docs/11/protocol-message-formats.html) for its communication
 
-`pgagroal` will work with any [PostgreSQL](https://www.postgresql.org) compliant driver, for example
+[**pgagroal**](https://github.com/agroal/pgagroal) will work with any [PostgreSQL](https://www.postgresql.org) compliant driver, for example
 [pgjdbc](https://jdbc.postgresql.org/), [Npgsql](https://www.npgsql.org/) and [pq](https://github.com/lib/pq).
 
-See [Architecture](./doc/ARCHITECTURE.md) for the architecture of `pgagroal`.
+See [Architecture](./doc/ARCHITECTURE.md) for the architecture of [**pgagroal**](https://github.com/agroal/pgagroal).
 
 ## Tested platforms
 
@@ -59,7 +59,7 @@ See [Architecture](./doc/ARCHITECTURE.md) for the architecture of `pgagroal`.
 
 ## Compiling the source
 
-`pgagroal` requires
+[**pgagroal**](https://github.com/agroal/pgagroal) requires
 
 * [gcc 8+](https://gcc.gnu.org) (C17)
 * [cmake](https://cmake.org)
@@ -78,10 +78,10 @@ can be installed via `dnf(8)` as follows:
 dnf install git gcc cmake make    \
             libev libev-devel     \
             openssl openssl-devel \
-	    systemd systemd-devel \
-	    python3-docutils      \
-	    libatomic             \
-	    cjson cjson-devel
+            systemd systemd-devel \
+            python3-docutils      \
+            libatomic             \
+            cjson cjson-devel
 ```
 
 Please note that, on Rocky Linux, in order to install the `python3-docutils`
@@ -96,7 +96,7 @@ Alternatively to GCC, [clang 8+](https://clang.llvm.org/) can be used.
 
 ### Release build
 
-The following commands will install `pgagroal` in the `/usr/local` hierarchy
+The following commands will install [**pgagroal**](https://github.com/agroal/pgagroal) in the `/usr/local` hierarchy
 and run the default configuration.
 
 ```sh
@@ -110,11 +110,11 @@ sudo make install
 /usr/local/bin/pgagroal -c /usr/local/etc/pgagroal/pgagroal.conf -a /usr/local/etc/pgagroal/pgagroal_hba.conf
 ```
 
-See [RPM](./doc/RPM.md) for how to build a RPM of `pgagroal`.
+See [RPM](./doc/RPM.md) for how to build a RPM of [**pgagroal**](https://github.com/agroal/pgagroal).
 
 ### Debug build
 
-The following commands will create a `DEBUG` version of `pgagroal`.
+The following commands will create a `DEBUG` version of [**pgagroal**](https://github.com/agroal/pgagroal).
 
 ```sh
 git clone https://github.com/agroal/pgagroal.git
@@ -132,7 +132,7 @@ Remember to set the `log_level` configuration option to `debug5`.
 
 ## Contributing
 
-Contributions to `pgagroal` are managed on [GitHub.com](https://github.com/agroal/pgagroal/)
+Contributions to [**pgagroal**](https://github.com/agroal/pgagroal) are managed on [GitHub.com](https://github.com/agroal/pgagroal/)
 
 * [Ask a question](https://github.com/agroal/pgagroal/discussions)
 * [Raise an issue](https://github.com/agroal/pgagroal/issues)

cmake/FindPandoc.cmake

@@ -0,0 +1,38 @@
+#
+# pandoc Support
+#
+
+find_program(PANDOC_EXECUTABLE 
+  NAMES pandoc
+)
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(Pandoc DEFAULT_MSG 
+                                    PANDOC_EXECUTABLE)
+
+if(PANDOC_FOUND)
+  # check for eisvogel.latex
+  execute_process(
+    COMMAND ${PANDOC_EXECUTABLE} --version
+    OUTPUT_VARIABLE pandoc_output
+    RESULT_VARIABLE result
+  )
+  string(REGEX MATCH "User data directory: ([^\n\r]*)" _ ${pandoc_output})
+
+  if (NOT CMAKE_MATCH_COUNT)
+    string(REGEX MATCH "Default user data directory: ([^ ]+)" _ ${pandoc_output})
+    set(EISVOGEL_TEMPLATE_PATH "${CMAKE_MATCH_1}/templates/eisvogel.latex")
+  else()
+    set(EISVOGEL_TEMPLATE_PATH "${CMAKE_MATCH_1}/templates/eisvogel.latex")
+  endif()
+
+  if(EXISTS "${EISVOGEL_TEMPLATE_PATH}")
+    message(STATUS "Found eisvogel template at ${EISVOGEL_TEMPLATE_PATH}")
+  else()
+    message(STATUS "eisvogel template not found at ${EISVOGEL_TEMPLATE_PATH}. The generation process will be skipped.")
+    set(generation FALSE)
+  endif()
+
+endif()
+
+mark_as_advanced(PANDOC_EXECUTABLE)

cmake/FindPdflatex.cmake

@@ -0,0 +1,58 @@
+#
+# pdflatex Support
+#
+
+find_program(PDFLATEX_EXECUTABLE 
+  NAMES pdflatex
+)
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(Pdflatex DEFAULT_MSG
+                                  PDFLATEX_EXECUTABLE)
+
+if(PDFLATEX_FOUND)
+
+  # check for kpsewhich
+  find_program(KPSEWHICH kpsewhich)
+  if(NOT KPSEWHICH)
+    set(generation FALSE)
+    message(STATUS "kpsewhich not found. The generation process will be skipped.")
+    return()
+  endif()
+
+  # check for packages
+  set(check_next TRUE)
+  macro(check_latex_package PACKAGE_NAME)
+    if(check_next)
+      execute_process(
+        COMMAND ${KPSEWHICH} ${PACKAGE_NAME}
+        OUTPUT_VARIABLE PATH
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+      )
+      if(NOT PATH)
+        set(generation FALSE)
+        message(STATUS "${PACKAGE_NAME} not found. The generation process will be skipped.")
+        set(check_next FALSE)  # Disable further checks
+      else()
+        message(STATUS "${PACKAGE_NAME} found at: ${PATH}")
+      endif()
+    endif()
+  endmacro()
+
+  # Use the macro to check for packages
+  check_latex_package("footnote.sty")
+  check_latex_package("footnotebackref.sty")
+  check_latex_package("pagecolor.sty")
+  check_latex_package("hardwrap.sty")
+  check_latex_package("mdframed.sty")
+  check_latex_package("sourcesanspro.sty")
+  check_latex_package("ly1enc.def")
+  check_latex_package("sourcecodepro.sty")
+  check_latex_package("titling.sty")
+  check_latex_package("csquotes.sty")
+  check_latex_package("zref-abspage.sty")
+  check_latex_package("needspace.sty")
+
+endif()
+
+mark_as_advanced(PDFLATEX_EXECUTABLE)

doc/ADMIN.md

@@ -1,7 +1,7 @@
 # `pgagroal-admin` user guide
 
 `pgagroal-admin` is a command line interface to manage users known
-to the `pgagroal` connection pooler.
+to the [**pgagroal**](https://github.com/agroal/pgagroal) connection pooler.
 The executable accepts a set of options, as well as a command to execute.
 If no command is provided, the program will show the help screen.
 
@@ -63,7 +63,7 @@ that is the "container" for users' credentials.
 ## Deprecated commands
 
 The following commands have been deprecated and will be removed
-in later releases of `pgagroal`.
+in later releases of [**pgagroal**](https://github.com/agroal/pgagroal).
 For each command, this is the corresponding current mapping
 to the working command:
 

doc/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-`pgagroal` use a process model (`fork()`), where each process handles one connection to [PostgreSQL](https://www.postgresql.org).
+[**pgagroal**](https://github.com/agroal/pgagroal) use a process model (`fork()`), where each process handles one connection to [PostgreSQL](https://www.postgresql.org).
 This was done such a potential crash on one connection won't take the entire pool down.
 
 The main process is defined in [main.c](../src/main.c). When a client connects it is processed in its own process, which
@@ -12,10 +12,10 @@ Once the client disconnects the connection is put back in the pool, and the chil
 
 ## Shared memory
 
-A memory segment ([shmem.h](../src/include/shmem.h)) is shared among all processes which contains the `pgagroal`
+A memory segment ([shmem.h](../src/include/shmem.h)) is shared among all processes which contains the [**pgagroal**](https://github.com/agroal/pgagroal)
 state containing the configuration of the pool, the list of servers and the state of each connection.
 
-The configuration of `pgagroal` (`struct configuration`), the configuration of the servers (`struct server`) and
+The configuration of [**pgagroal**](https://github.com/agroal/pgagroal) (`struct configuration`), the configuration of the servers (`struct server`) and
 the state of each connection (`struct connection`) is initialized in this shared memory segment.
 These structs are all defined in [pgagroal.h](../src/include/pgagroal.h).
 
@@ -43,7 +43,7 @@ These state are defined in [pgagroal.h](../src/include/pgagroal.h).
 
 ## Pool
 
-The `pgagroal` pool API is defined in [pool.h](../src/include/pool.h) ([pool.c](../src/libpgagroal/pool.c)).
+The [**pgagroal**](https://github.com/agroal/pgagroal) pool API is defined in [pool.h](../src/include/pool.h) ([pool.c](../src/libpgagroal/pool.c)).
 
 This API defines the functionality of the pool such as getting a connection from the pool, and returning it.
 There is no ordering among processes, so a newly created process can obtain a connection before an older process.
@@ -69,13 +69,13 @@ The memory interface is defined in [memory.h](../src/include/memory.h) ([memory.
 
 ## Management
 
-`pgagroal` has a management interface which serves two purposes.
+[**pgagroal**](https://github.com/agroal/pgagroal) has a management interface which serves two purposes.
 
 First, it defines the administrator abilities that can be performed on the pool when it is running. This include
 for example flushing the pool. The `pgagroal-cli` program is used for these operations ([cli.c](../src/cli.c)).
 
 Second, the interface is used internally to transfer the connection (socket descriptor) from the child process
-to the main `pgagroal` process after a new connection has been created. This is necessary since the socket descriptor
+to the main [**pgagroal**](https://github.com/agroal/pgagroal) process after a new connection has been created. This is necessary since the socket descriptor
 needs to be available to subsequent client and hence processes.
 
 The management interface use Unix Domain Socket for communication.
@@ -110,7 +110,7 @@ is ready. The main loop handles the system wide "services" such as idle timeout
 
 ## Pipeline
 
-`pgagroal` has the concept of a pipeline that defines how communication is routed from the client through `pgagroal` to
+[**pgagroal**](https://github.com/agroal/pgagroal) has the concept of a pipeline that defines how communication is routed from the client through [**pgagroal**](https://github.com/agroal/pgagroal) to
 [PostgreSQL](https://www.postgresql.org). Likewise in the other direction.
 
 A pipeline is defined by
@@ -136,8 +136,8 @@ The functions in the pipeline are defined as
 |----------|-------------|
 | `initialize` | Global initialization of the pipeline, may return a pointer to a shared memory segment |
 | `start` | Called when the pipeline instance is started |
-| `client` | Client to `pgagroal` communication |
-| `server` | [PostgreSQL](https://www.postgresql.org) to `pgagroal` communication |
+| `client` | Client to [**pgagroal**](https://github.com/agroal/pgagroal) communication |
+| `server` | [PostgreSQL](https://www.postgresql.org) to [**pgagroal**](https://github.com/agroal/pgagroal) communication |
 | `stop` | Called when the pipeline instance is stopped |
 | `destroy` | Global destruction of the pipeline |
 | `periodic` | Called periodic |
@@ -159,7 +159,7 @@ defined in [worker.h](../src/include/worker.h).
 
 ### Performance pipeline
 
-One of the goals for `pgagroal` is performance, so the performance pipeline will only look for the
+One of the goals for [**pgagroal**](https://github.com/agroal/pgagroal) is performance, so the performance pipeline will only look for the
 [`Terminate`](https://www.postgresql.org/docs/11/protocol-message-formats.html) message from the client and act on that.
 Likewise the performance pipeline will only look for `FATAL` errors from the server. This makes the pipeline very fast, since there
 is a minimum overhead in the interaction.
@@ -170,8 +170,8 @@ The pipeline is defined in [pipeline_perf.c](../src/libpgagroal/pipeline_perf.c)
 |----------|-------------|
 | `performance_initialize` | Nothing |
 | `performance_start` | Nothing |
-| `performance_client` | Client to `pgagroal` communication |
-| `performance_server` | [PostgreSQL](https://www.postgresql.org) to `pgagroal` communication |
+| `performance_client` | Client to [**pgagroal**](https://github.com/agroal/pgagroal) communication |
+| `performance_server` | [PostgreSQL](https://www.postgresql.org) to [**pgagroal**](https://github.com/agroal/pgagroal) communication |
 | `performance_stop` | Nothing |
 | `performance_destroy` | Nothing |
 | `performance_periodic` | Nothing |
@@ -187,8 +187,8 @@ The pipeline is defined in [pipeline_session.c](../src/libpgagroal/pipeline_sess
 |----------|-------------|
 | `session_initialize` | Initialize memory segment if disconnect_client is active |
 | `session_start` | Prepares the client segment if disconnect_client is active |
-| `session_client` | Client to `pgagroal` communication |
-| `session_server` | [PostgreSQL](https://www.postgresql.org) to `pgagroal` communication |
+| `session_client` | Client to [**pgagroal**](https://github.com/agroal/pgagroal) communication |
+| `session_server` | [PostgreSQL](https://www.postgresql.org) to [**pgagroal**](https://github.com/agroal/pgagroal) communication |
 | `session_stop` | Updates the client segment if disconnect_client is active |
 | `session_destroy` | Destroys memory segment if initialized |
 | `session_periodic` | Checks if clients should be disconnected |
@@ -210,29 +210,29 @@ The pipeline is defined in [pipeline_transaction.c](../src/libpgagroal/pipeline_
 |----------|-------------|
 | `transaction_initialize` | Nothing |
 | `transaction_start` | Setup process variables and returns the connection to the pool |
-| `transaction_client` | Client to `pgagroal` communication. Obtain connection if needed |
-| `transaction_server` | [PostgreSQL](https://www.postgresql.org) to `pgagroal` communication. Keep track of message headers |
+| `transaction_client` | Client to [**pgagroal**](https://github.com/agroal/pgagroal) communication. Obtain connection if needed |
+| `transaction_server` | [PostgreSQL](https://www.postgresql.org) to [**pgagroal**](https://github.com/agroal/pgagroal) communication. Keep track of message headers |
 | `transaction_stop` | Return connection to the pool if needed. Possible rollback of active transaction |
 | `transaction_destroy` | Nothing |
 | `transaction_periodic` | Nothing |
 
 ## Signals
 
-The main process of `pgagroal` supports the following signals `SIGTERM`, `SIGINT` and `SIGALRM`
-as a mechanism for shutting down. The `SIGTRAP` signal will put `pgagroal` into graceful shutdown, meaning that
+The main process of [**pgagroal**](https://github.com/agroal/pgagroal) supports the following signals `SIGTERM`, `SIGINT` and `SIGALRM`
+as a mechanism for shutting down. The `SIGTRAP` signal will put [**pgagroal**](https://github.com/agroal/pgagroal) into graceful shutdown, meaning that
 exisiting connections are allowed to finish their session. The `SIGABRT` is used to request a core dump (`abort()`).
 The `SIGHUP` signal will trigger a reload of the configuration.
 
 The child processes support `SIGQUIT` as a mechanism to shutdown. This will not shutdown the pool itself.
 
-It should not be needed to use `SIGKILL` for `pgagroal`. Please, consider using `SIGABRT` instead, and share the
-core dump and debug logs with the `pgagroal` community.
+It should not be needed to use `SIGKILL` for [**pgagroal**](https://github.com/agroal/pgagroal). Please, consider using `SIGABRT` instead, and share the
+core dump and debug logs with the [**pgagroal**](https://github.com/agroal/pgagroal) community.
 
 ## Reload
 
 The `SIGHUP` signal will trigger a reload of the configuration.
 
-However, some configuration settings requires a full restart of `pgagroal` in order to take effect. These are
+However, some configuration settings requires a full restart of [**pgagroal**](https://github.com/agroal/pgagroal) in order to take effect. These are
 
 * `hugepage`
 * `libev`