Migrate docs to pydocca

Improved reference docs linkage and fixed several formatting issues
Removed obsolete performance warning about close_statement

close #334

Author: anarthal

.drone.star

@@ -6,7 +6,7 @@
 #
 
 _triggers = { "branch": [ "master", "develop" ] }
-_container_tag = '1e06ba22fc5ab038a3c4ce4a73d0d624848c8f70'
+_container_tag = 'ee78aa84c0231742deb853556da1d56f5a2b8148'
 _win_container_tag = 'e7bd656c3515263f9b3c69a2d73d045f6a0fed72'
 
 

.github/workflows/coverage.yml

@@ -18,12 +18,12 @@ jobs:
   coverage:
     runs-on: ubuntu-latest
     container:
-      image: ghcr.io/anarthal-containers/build-gcc13:1e06ba22fc5ab038a3c4ce4a73d0d624848c8f70
+      image: ghcr.io/anarthal-containers/build-gcc13:ee78aa84c0231742deb853556da1d56f5a2b8148
       volumes:
         - /var/run/mysqld:/var/run/mysqld
     services:
       mysql:
-        image: ghcr.io/anarthal-containers/ci-db:mysql-8.4.1-1e06ba22fc5ab038a3c4ce4a73d0d624848c8f70
+        image: ghcr.io/anarthal-containers/ci-db:mysql-8.4.1-ee78aa84c0231742deb853556da1d56f5a2b8148
         ports:
           - 3306:3306
         volumes:

.github/workflows/fuzz.yml

@@ -20,12 +20,12 @@ jobs:
   fuzz:
     runs-on: ubuntu-latest
     container:
-      image: ghcr.io/anarthal-containers/build-clang18:1e06ba22fc5ab038a3c4ce4a73d0d624848c8f70
+      image: ghcr.io/anarthal-containers/build-clang18:ee78aa84c0231742deb853556da1d56f5a2b8148
       volumes:
         - /var/run/mysqld:/var/run/mysqld
     services:
       mysql:
-        image: ghcr.io/anarthal-containers/ci-db:mysql-8.4.1-1e06ba22fc5ab038a3c4ce4a73d0d624848c8f70
+        image: ghcr.io/anarthal-containers/ci-db:mysql-8.4.1-ee78aa84c0231742deb853556da1d56f5a2b8148
         ports:
           - 3306:3306
         volumes:

doc/Jamfile

@@ -10,6 +10,7 @@ project mysql/doc ;
 
 import boostbook ;
 import os ;
+import path ;
 import-search /boost/docca ;
 import docca ;
 
@@ -26,9 +27,11 @@ local doxygen_exclussions =
     src.hpp
 ;
 
-docca.reference reference.qbk
+local include-prefix = [ path.root $(__file__:D) [ path.pwd ] ] ;
+include-prefix = [ path.native $(include-prefix:D)/include ] ;
+
+docca.pyreference reference.qbk
     :
-        xsl/custom-overrides.xsl
         [ glob-tree-ex ../include/boost/mysql : *.hpp : $(doxygen_exclussions) ]
     :
         <doxygen:param>PROJECT_NAME=MySQL
@@ -38,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 \\
@@ -75,7 +79,6 @@ 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>AUTOLINK_SUPPORT=NO
         <doxygen:param>EXTRACT_ALL=NO
         <doxygen:param>EXTRACT_PRIVATE=NO
@@ -91,8 +94,9 @@ 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
+
+        <docca:config>config.json
     ;
 
 install images

doc/config.json

@@ -0,0 +1,26 @@
+{
+    "include_private": false,
+    "legacy_behavior": false,
+    "external_marker": "!EXTERNAL!",
+    "link_prefix": "mysql.ref.",
+    "default_namespace": "boost::mysql",
+    "convenience_header": "boost/mysql.hpp",
+    "replace_strings": {
+        "__see_below__": "``['see-below]``",
+        "\\bclass CompletionToken\\b": "class __CompletionToken__",
+        "\\bclass ExecutionContext\\b": "class __ExecutionContext__",
+        "\\bclass ExecutionRequest\\b": "class __ExecutionRequest__",
+        "\\bclass ExecutionStateType\\b": "class __ExecutionStateType__",
+        "\\bclass Executor\\b": "class __Executor__",
+        "\\bclass FieldViewFwdIterator\\b": "class __FieldViewFwdIterator__",
+        "\\bclass Formattable\\b": "class __Formattable__",
+        "\\bclass OutputString\\b": "class __OutputString__",
+        "\\bclass ResultsType\\b": "class __ResultsType__",
+        "\\bclass SocketStream\\b": "class __SocketStream__",
+        "\\bclass StaticRow\\b": "class __StaticRow__",
+        "\\bclass Stream\\b": "class __Stream__",
+        "\\bclass WritableField\\b": "class __WritableField__",
+        "\\bclass WritableFieldTuple\\b": "class __WritableFieldTuple__",
+        "\\bBOOST_MYSQL_FORMATTABLE\\b": "class"
+    }
+}

doc/qbk/23_sql_formatting_advanced.qbk

@@ -107,7 +107,7 @@ You don't have to use exceptions, though. [reflink basic_format_context] and
 instead.
 
 [reflink basic_format_context] contains an error code that is set when formatting
-a value fails. This is called the ['error state], and can be queried using [refmem basic_format_context error_state].
+a value fails. This is called the ['error state], and can be queried using [refmem format_context_base error_state].
 When [refmem basic_format_context get] is called (after all individual values have been formatted),
 the error state is checked. The `system::result` returned by `get` will contain the error
 state if it was set, or the generated query if it was not:

doc/xsl/custom-overrides.xsl

@@ -32,7 +32,6 @@ enum class address_type
  * \brief (EXPERIMENTAL) A host and port identifying how to connect to a MySQL server.
  * \details
  * This is an owning type with value semantics.
- * \see any_address
  *
  * \par Experimental
  * This part of the API is experimental, and may change in successive
@@ -58,7 +57,6 @@ struct host_and_port
  * This type is defined in all systems, regardless of their UNIX socket support.
  * \n
  * This is an owning type with value semantics.
- * \see any_address
  */
 struct unix_path
 {

include/boost/mysql/any_address.hpp

@@ -49,10 +49,6 @@ struct character_set
      * trying to interpret the first character, it should return 0 to signal the error.
      * \n
      * This function must not throw exceptions or have side effects.
-     * \n
-     * \par Function signature
-     * The function signature should be:
-     * `std::size_t (*next_char)(boost::span<const unsigned char> r)`.
      */
     std::size_t (*next_char)(span<const unsigned char>);
 };

include/boost/mysql/character_set.hpp

@@ -23,19 +23,25 @@ namespace mysql {
  */
 enum class client_errc : int
 {
-    /// An incomplete message was received from the server (indicates a deserialization error or
-    /// packet mismatch).
+    /**
+     * \brief An incomplete message was received from the server (indicates a deserialization error or
+     * packet mismatch).
+     */
     incomplete_message = 1,
 
-    /// An unexpected value was found in a server-received message (indicates a deserialization
-    /// error or packet mismatch).
+    /**
+     * \brief An unexpected value was found in a server-received message (indicates a deserialization
+     * error or packet mismatch).
+     */
     protocol_value_error,
 
     /// The server does not support the minimum required capabilities to establish the connection.
     server_unsupported,
 
-    /// Unexpected extra bytes at the end of a message were received (indicates a deserialization
-    /// error or packet mismatch).
+    /**
+     * \brief Unexpected extra bytes at the end of a message were received (indicates a deserialization
+     * error or packet mismatch).
+     */
     extra_bytes,
 
     /// Mismatched sequence numbers (usually caused by a packet mismatch).
@@ -47,22 +53,29 @@ enum class client_errc : int
     /// The authentication plugin requires the connection to use SSL.
     auth_plugin_requires_ssl,
 
-    /// The number of parameters passed to the prepared statement does not match the number of
-    /// actual parameters.
+    /**
+     * \brief The number of parameters passed to the prepared statement does not match the number of
+     * actual parameters.
+     */
     wrong_num_params,
 
     /// The connection mandates SSL, but the server doesn't accept SSL connections.
     server_doesnt_support_ssl,
 
-    /// The static interface detected a mismatch between your C++ type definitions and what the server
-    /// returned in the query.
+    /**
+     * \brief
+     * The static interface detected a mismatch between your C++ type definitions and what the server
+     * returned in the query.
+     */
     metadata_check_failed,
 
-    /// The static interface detected a mismatch between the number of row types passed to `static_results`
-    /// or `static_execution_state` and the number of resultsets returned by your query.
+    /**
+     * \brief The static interface detected a mismatch between the number of row types passed to
+     * \ref static_results or \ref static_execution_state and the number of resultsets returned by your query.
+     */
     num_resultsets_mismatch,
 
-    /// The StaticRow type passed to read_some_rows does not correspond to the resultset type being read.
+    /// The `StaticRow` type passed to read_some_rows does not correspond to the resultset type being read.
     row_type_mismatch,
 
     /// The static interface encountered an error when parsing a field into a C++ data structure.
@@ -74,8 +87,10 @@ enum class client_errc : int
     /// (EXPERIMENTAL) An operation controlled by Boost.MySQL was cancelled.
     cancelled,
 
-    /// (EXPERIMENTAL) Getting a connection from a connection_pool failed because the
-    /// pool is not running. Ensure that you're calling connection_pool::async_run.
+    /**
+     * \brief (EXPERIMENTAL) Getting a connection from a connection_pool failed because the
+     * pool is not running. Ensure that you're calling connection_pool::async_run.
+     */
     pool_not_running,
 
     /// (EXPERIMENTAL) An invalid byte sequence was found while trying to decode a string.
@@ -87,8 +102,10 @@ enum class client_errc : int
     /// (EXPERIMENTAL) A format string containing invalid syntax was provided to a SQL formatting function.
     format_string_invalid_syntax,
 
-    /// (EXPERIMENTAL) A format string with an invalid byte sequence was provided to a SQL formatting
-    /// function.
+    /**
+     * \brief (EXPERIMENTAL) A format string with an invalid byte sequence was provided to a SQL formatting
+     * function.
+     */
     format_string_invalid_encoding,
 
     /// (EXPERIMENTAL) A format string mixes manual (e.g. {0}) and automatic (e.g. {}) indexing.
@@ -97,16 +114,23 @@ enum class client_errc : int
     /// (EXPERIMENTAL) The supplied format specifier (e.g. {:i}) is not supported by the type being formatted.
     format_string_invalid_specifier,
 
-    /// (EXPERIMENTAL) A format argument referenced by a format string was not found. Check the number
-    /// of format arguments passed and their names.
+    /**
+     * \brief (EXPERIMENTAL) A format argument referenced by a format string was not found. Check the number
+     * of format arguments passed and their names.
+     */
     format_arg_not_found,
 
-    /// (EXPERIMENTAL) The character set used by the connection is not known by the client. Use
-    /// set_character_set or async_set_character_set before invoking operations that require a known charset.
+    /**
+     * \brief (EXPERIMENTAL) The character set used by the connection is not known by the client. Use
+     * \ref any_connection::set_character_set or \ref any_connection::async_set_character_set
+     * before invoking operations that require a known charset.
+     */
     unknown_character_set,
 
-    /// (EXPERIMENTAL) An operation attempted to read or write a packet larger than the maximum buffer size.
-    /// Try increasing \ref any_connection_params::max_buffer_size.
+    /**
+     * \brief (EXPERIMENTAL) An operation attempted to read or write a packet larger than the maximum buffer
+     * size. Try increasing \ref any_connection_params::max_buffer_size.
+     */
     max_buffer_size_exceeded,
 };