Migrated docs to Asciidoc, Antora and MrDocs

.clang-format

@@ -85,7 +85,7 @@ BreakConstructorInitializersBeforeComma: false
 BreakConstructorInitializers: BeforeColon
 BreakAfterJavaFieldAnnotations: false
 BreakStringLiterals: true
-CommentPragmas: '(^ IWYU pragma:)|(^\\copydoc )|(^ ?\\n)'
+CommentPragmas: '(^ IWYU pragma:)|(^\\copydoc )|(^ ?\\n)|(^<a href=)'
 CompactNamespaces: false
 ConstructorInitializerAllOnOneLineOrOnePerLine: true
 ConstructorInitializerIndentWidth: 4

.gitignore

@@ -14,3 +14,6 @@ compile_commands.json
 .cache/
 __build*__/
 __pycache__/
+node_modules/
+/doc/build/
+/doc/reference-output/

doc/CMakeLists.txt

@@ -0,0 +1,25 @@
+#
+# Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+cmake_minimum_required(VERSION 3.8...3.22)
+
+# Project
+project(boost_mysql_mrdocs LANGUAGES CXX)
+
+# MrDocs forces CMAKE_EXPORT_COMPILE_COMMANDS=ON, incorrectly
+# causing all targets to be dumped to the compilation database.
+# Disable this setting so we can set EXPORT_COMPILE_COMMANDS
+# only to our target of interest
+set(CMAKE_EXPORT_COMPILE_COMMANDS OFF)
+
+# Add Boost
+add_subdirectory($ENV{BOOST_SRC_DIR} deps/boost)
+
+# Add the target for mrdocs to analyze
+add_executable(mrdocs mrdocs.cpp)
+target_link_libraries(mrdocs PRIVATE Boost::mysql)
+set_target_properties(mrdocs PROPERTIES EXPORT_COMPILE_COMMANDS ON)

doc/antora.yml

@@ -0,0 +1,15 @@
+#
+# Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+name: mysql
+title: Boost.MySQL
+version: ~
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  cpp-reference:
+    config: doc/mrdocs.yml

doc/local-playbook.yml

@@ -0,0 +1,47 @@
+#
+# Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+site:
+  url: https://test.com/ # TODO: change this
+  title: Boost.MySQL documentation
+  robots: allow
+
+antora:
+  extensions:
+    - require: '@cppalliance/antora-cpp-tagfiles-extension'
+      cpp-tagfiles:
+        using-namespaces:
+          - 'boost::'
+    - require: '@cppalliance/antora-cpp-reference-extension'
+      dependencies:
+        - name: 'boost'
+          repo: 'https://github.com/boostorg/boost.git'
+          tag: 'develop'
+          variable: 'BOOST_SRC_DIR'
+          system-env: 'BOOST_SRC_DIR'
+
+asciidoc:
+  attributes:
+    # Enable pagination
+    page-pagination: ''
+  extensions:
+    - '@cppalliance/asciidoctor-boost-links'
+    - '@asciidoctor/tabs'
+
+# Libraries that support Antora should be included here
+content:
+  sources:
+    - url: ..
+      start_path: doc
+
+ui: 
+  bundle:
+    url: https://github.com/boostorg/website-v2-docs/releases/download/ui-master/ui-bundle.zip
+    snapshot: true
+
+output:
+  dir: ../__build/doc

doc/modules/ROOT/nav.adoc

@@ -0,0 +1,4 @@
+* xref:index.adoc[Introduction]
+* xref:overview.adoc[]
+* xref:reference:index.adoc[Reference]
+

doc/modules/ROOT/pages/index.adoc

@@ -0,0 +1,105 @@
+
+[#intro]
+= Introduction
+
+Boost.MySQL is a pass:[C++11] client for the https://www.mysql.com/[MySQL] and https://mariadb.com/[MariaDB] database servers, based on Boost.Asio.
+
+== Motivation
+
+MySQL and MariaDB are widespread SQL database servers. MySQL
+clients connect to the server in order to issue SQL queries. For this
+purpose, MySQL employs a dedicated protocol. Boost.MySQL is an
+implementation of the client side of this protocol.
+
+This library is a full implementation of the
+https://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_PROTOCOL.html[MySQL client/server protocol].
+It aims to expose the protocol primitives in an efficient but easy-to-use way.
+It is similar in scope to the official https://dev.mysql.com/doc/c-api/8.0/en/[libmysqlclient],
+but interoperable with Asio, safer and more expressive. Note that Boost.MySQL
+*does not use libmysqlclient*: it's a full implementation of the MySQL protocol, which makes
+it natively compatible with Asio.
+
+This library is relatively low level. It gives you access to text SQL queries and
+prepared statements. Don't expect an ORM. xref:overview.adoc[This section] presents a quick tour
+over the main library capabilities.
+
+The design goals of this library are:
+
+- *Interoperability with Asio*: this library employs the same principles as Boost.Asio and Boost.Beast.
+  Users of any of these libraries will immediately understand Boost.MySQL, and will have it easy
+  to integrate it in their programs.
+* *Basis for further abstraction*: it allows efficient access to the MySQL client/server protocol
+  so it can be used by higher level components as a building block. Do a single thing and do it well.
+* *Efficiency*.
+* *Ease of use*: the MySQL protocol is full of pitfalls. We believe in simplicity. While retaining
+  control over the important parts, the library hides as much complexity from the protocol as possible.
+
+Non-goals:
+
+* *Being an ORM*.
+* *Portability to other SQL databases*. This library focuses on MySQL. It won't work with Postgres
+  or SQLite.
+
+== When to use
+
+If any of the following statements is true, you may consider using Boost.MySQL:
+
+* Your application uses Boost.Asio and you need to access a MySQL server.
+* You need asynchronous access to a MySQL server from a pass:[C++] application.
+* You need efficient access to a MySQL server from a pass:[C++] application.
+* You need a BSL-licensed library to access your MySQL server.
+* You are writing a higher-level database access library, like an ORM.
+
+Use cases may include web servers, ETL processes and IoT systems.
+
+It may not be a good fit for you if:
+
+* You only need synchronous access to a MySQL server and efficiency doesn't matter
+  to your application. The official client libraries may be better suited for you, in this case.
+* You need homogeneous SQL access to different SQL databases (and not only MySQL access).
+  You may find more value in using https://github.com/rbock/sqlpp11[sqlpp11] or a similar wrapper
+  library.
+
+
+
+== Tested compilers and systems
+
+Boost.MySQL is tested under the following compilers:
+
+* gcc 5.4 (Linux)
+* gcc 6.5 (Linux)
+* gcc 10.3 (Linux)
+* gcc 11.2 (Linux)
+* gcc 13.0 (Linux)
+* gcc 14.0 (Linux)
+* clang 3.6 (Linux)
+* clang 7.0 (Linux)
+* clang 11.0 (Linux)
+* clang 14.0 (Linux)
+* clang 16.0 (Linux)
+* clang 17.0 (Linux)
+* clang 18.0 (Linux)
+* Apple clang 14.0 (OSX)
+* MSVC 14.1 - Visual Studio 2017 (Windows)
+* MSVC 14.2 - Visual Studio 2019 (Windows)
+* MSVC 14.3 - Visual Studio 2022 (Windows)
+
+And with the following RDBMS systems:
+
+* MySQL v5.7.41.
+* MySQL v8.4.1.
+* MariaDB v11.4.2.
+
+== Acknowledgements
+
+I would like to specially acknowledge https://github.com/madmongo1[Richard Hodges] ([email protected])
+for his invaluable technical guidance during development. Thanks also to
+Christian Mazakas for his ideas in early stages, and to
+https://github.com/klemens-morgenstern[Klemens Morgenstern] and
+and https://github.com/vinniefalco[Vinnie Falco] for his techincal advice.
+Without you, this library would not exist.
+
+Finally, thanks to https://github.com/chriskohlhoff[Christopher Kohlhoff]
+for his awesome Asio library, and to https://github.com/HowardHinnant[Howard Hinnant]
+for his date algorithms, shamelessly copied in this lib.
+

doc/modules/ROOT/pages/overview.adoc

@@ -0,0 +1,3 @@
+= Overview
+
+Under construction

doc/modules/ROOT/pages/reference.adoc

@@ -0,0 +1,24 @@
+//
+// Copyright (c) 2023 Alan de Freitas ([email protected])
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/boostorg/url
+//
+
+
+[#reference]
+= Reference
+
+
+
+[width=100%]
+|===
+1+| *Types*
+
+xref:reference:boost/mysql/host_and_port.adoc[`host_and_port`]
+
+
+|===
+

doc/mrdocs.cpp

@@ -0,0 +1,9 @@
+//
+// Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#define BOOST_MYSQL_SEPARATE_COMPILATION
+#include <boost/mysql.hpp>

doc/mrdocs.yml

@@ -0,0 +1,26 @@
+#
+# Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+source-root: ../include
+compilation-database: ./CMakeLists.txt
+multipage: true
+include-symbols:
+  - "boost::mysql::**"
+exclude-symbols:
+  - boost::mysql::format_context_base::format_context_base
+  - boost::mysql::format_context_base::assign
+  - "boost::mysql::detail::**"
+  - "boost::mysql::mysql_server_errc"
+  - "boost::mysql::mariadb_server_errc"
+  - "boost::mysql::mysql_collations"
+  - "boost::mysql::mariadb_collations"
+  - "boost::mysql::formatter<*>"
+implementation-defined:
+  - "boost::mysql::impl_defined::**" # Matching symbols need to not be excluded. Including all detail is slow and causes trouble
+verbose: true
+use-system-libc: true
+base-url: https://github.com/boostorg/mysql/blob/master/include/