Switch to asciidoc

.gitignore

@@ -14,3 +14,5 @@ compile_commands.json
 .cache/
 __build*__/
 __pycache__/
+node_modules/
+doc/adoc/mysql/modules/reference/

doc/Jamfile

@@ -10,6 +10,7 @@ project mysql/doc ;
 
 import boostbook ;
 import os ;
+import path ;
 import ../../../tools/docca/docca.jam ;
 
 
@@ -25,6 +26,9 @@ local doxygen_exclussions =
     src.hpp
 ;
 
+local include-prefix = [ path.root $(__file__:D) [ path.pwd ] ] ;
+include-prefix = [ path.native $(include-prefix:D)/include ] ;
+
 docca.reference reference.qbk
     :
         xsl/custom-overrides.xsl
@@ -37,6 +41,7 @@ docca.reference reference.qbk
         <doxygen:param>MACRO_EXPANSION=YES
         <doxygen:param>EXPAND_ONLY_PREDEF=YES
         <doxygen:param>SEARCH_INCLUDES=NO
+        <doxygen:param>STRIP_FROM_PATH=$(include-prefix)
         <doxygen:param>"PREDEFINED=\\
             BOOST_MYSQL_DOXYGEN \\
             __cpp_lib_string_view \\
@@ -74,7 +79,7 @@ docca.reference reference.qbk
         <doxygen:param>SKIP_FUNCTION_MACROS=NO
         <doxygen:param>OUTPUT_LANGUAGE=English
         <doxygen:param>ABBREVIATE_BRIEF=
-        <doxygen:param>INLINE_INHERITED_MEMB=YES
+        # <doxygen:param>INLINE_INHERITED_MEMB=YES
         <doxygen:param>AUTOLINK_SUPPORT=NO
         <doxygen:param>EXTRACT_ALL=NO
         <doxygen:param>EXTRACT_PRIVATE=NO
@@ -90,7 +95,6 @@ docca.reference reference.qbk
         <doxygen:param>SHOW_USED_FILES=NO
         <doxygen:param>SHOW_FILES=NO
         <doxygen:param>SHOW_NAMESPACES=NO
-        <doxygen:param>CLASS_DIAGRAMS=NO
         <doxygen:param>QUIET=YES
     ;
 

doc/adoc/mysql/antora.yml

@@ -0,0 +1,5 @@
+name: mysql
+title: Boost.MySQL
+version: ~
+nav:
+  - modules/ROOT/nav.adoc

doc/adoc/mysql/modules/ROOT/nav.adoc

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

doc/adoc/mysql/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/adoc/mysql/modules/ROOT/pages/overview.adoc

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

doc/supplemental-ui/css/custom.css

@@ -0,0 +1,155 @@
+
+.link-to-entity {
+    color: #0b0080 !important;
+}
+
+.keyword {
+    color: #0000dd !important;
+}
+
+.function-name {
+    color: #0645ad !important;
+    font-weight: bold !important;
+}
+
+.bg-white {
+    background: white !important;
+}
+
+.mt-0 {
+    margin-top: 0 !important;
+}
+
+.m-0 {
+  margin: 0 !important;
+}
+
+.pb-1 {
+  padding-bottom: 1vh !important;
+}
+
+.space-rows td {
+  padding-top: 2em !important;
+  padding-bottom: 2em !important;
+}
+
+.indent {
+    padding-left: 2em !important;
+}
+
+.doc {
+  hyphens: none !important;
+}
+
+.quickref article {
+  max-width: 80% !important;
+}
+
+.whitespace-nowrap {
+  white-space: nowrap !important;
+}
+
+/* highlight.js */
+
+/*! Adapted from the GitHub style by Vasily Polovnyov <[email protected]> */
+.hljs-comment,
+.hljs-quote {
+  color: #008000;
+  font-style: italic;
+}
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-subst {
+  color: #0000dd;
+  font-weight: var(--monospace-font-weight-bold);
+}
+
+.hljs-number,
+.hljs-literal,
+.hljs-variable,
+.hljs-template-variable,
+.hljs-tag .hljs-attr {
+  color: black;
+}
+
+.hljs-string,
+.hljs-doctag {
+  color: #d14;
+}
+
+.hljs-title,
+.hljs-section,
+.hljs-selector-id {
+  color: black;
+  font-weight: var(--monospace-font-weight-bold);
+}
+
+.hljs-subst {
+  font-weight: normal;
+}
+
+.hljs-type,
+.hljs-class .hljs-title {
+  color: black;
+  font-weight: var(--monospace-font-weight-bold);
+}
+
+.hljs-tag,
+.hljs-name,
+.hljs-attribute {
+  color: black;
+  font-weight: normal;
+}
+
+.hljs-regexp,
+.hljs-link {
+  color: #0b0080;
+}
+
+.hljs-symbol,
+.hljs-bullet {
+  color: black;
+}
+
+.hljs-built_in,
+.hljs-builtin-name {
+  color: #0086b3;
+}
+
+.hljs-meta {
+  color: #999;
+  font-weight: var(--monospace-font-weight-bold);
+}
+
+.hljs-deletion {
+  background: #fdd;
+}
+
+.hljs-addition {
+  background: #dfd;
+}
+
+.hljs-emphasis {
+  font-style: italic;
+}
+
+.hljs-strong {
+  font-weight: var(--monospace-font-weight-bold);
+}
+
+.highlightjs a {
+    color: #003080;
+}
+.highlightjs a:hover {
+    color: #003080;
+}
+
+.raw-code code {
+    background: white !important;
+    box-shadow: none !important;
+}
+
+.raw-code .source-toolbox {
+    display: none !important;
+}

doc/supplemental-ui/partials/head-styles.hbs

@@ -0,0 +1,2 @@
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/custom.css">