From c9f614ed5a76284f59975bfc50728a7c7196a5f2 Mon Sep 17 00:00:00 2001 From: Shawn Zhong Date: Sat, 29 Apr 2023 16:04:13 -0500 Subject: [PATCH] Improve docs --- doc/api.rst | 34 ++++++++++++++++++---------------- doc/fmt.less | 9 +++++++-- doc/index.rst | 2 +- doc/usage.rst | 12 ++++++------ include/fmt/format.h | 2 +- 5 files changed, 33 insertions(+), 26 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index 2e7f6d6d..8696d41c 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -39,14 +39,14 @@ similar to that of Python's `str.format `_. They take *fmt* and *args* as arguments. -*fmt* is a format string that contains literal text and replacement fields -surrounded by braces ``{}``. The fields are replaced with formatted arguments -in the resulting string. `~fmt::format_string` is a format string which can be -implicitly constructed from a string literal or a ``constexpr`` string and is -checked at compile time in C++20. To pass a runtime format string wrap it in -`fmt::runtime`. +* *fmt* is a format string that contains literal text and replacement fields + surrounded by braces ``{}``. The fields are replaced with formatted arguments + in the resulting string. `~fmt::format_string` is a format string which can be + implicitly constructed from a string literal or a ``constexpr`` string and is + checked at compile time in C++20. To pass a runtime format string wrap it in + `fmt::runtime`. -*args* is an argument list representing objects to be formatted. +* *args* is an argument list representing objects to be formatted. .. _format: @@ -75,7 +75,8 @@ Compile-time format string checks are enabled by default on compilers that support C++20 ``consteval``. On older compilers you can use the :ref:`FMT_STRING `: macro defined in ``fmt/format.h`` instead. -Unused arguments are allowed as in Python's `str.format` and ordinary functions. +Unused arguments are allowed as in Python's `str.format +`_ and ordinary functions. .. doxygenclass:: fmt::basic_format_string :members: @@ -347,13 +348,6 @@ Utilities .. doxygenfunction:: fmt::group_digits(T value) -> group_digits_view -.. doxygenclass:: fmt::detail::buffer - :members: - -.. doxygenclass:: fmt::basic_memory_buffer - :protected-members: - :members: - System Errors ------------- @@ -400,6 +394,13 @@ normally don't do any allocations for built-in and string types except for non-default floating-point formatting that occasionally falls back on ``sprintf``. +.. doxygenclass:: fmt::detail::buffer + :members: + +.. doxygenclass:: fmt::basic_memory_buffer + :protected-members: + :members: + Locale ------ @@ -509,6 +510,8 @@ Standard Library Types Formatting * `std::monostate `_ * `std::variant `_ * `std::optional `_ +* `std::error_code `_ +* `std::exception `_ Formatting Variants ------------------- @@ -569,7 +572,6 @@ System APIs :members: .. doxygenfunction:: fmt::windows_error - :members: .. _ostream-api: diff --git a/doc/fmt.less b/doc/fmt.less index 3a97b9fd..bb1289d0 100644 --- a/doc/fmt.less +++ b/doc/fmt.less @@ -41,8 +41,8 @@ div.sphinxsidebar { text-align: center; } -// Indent descriptions of classes, functions and macros. -.class dd, .function dd, .macro dd { +// Indent descriptions of classes, functions, macros, and structs. +.class dd, .function dd, .macro dd, .struct dd { margin-left: 20px; } @@ -56,6 +56,11 @@ div.sphinxsidebar { padding: 0; } +// Avoid the font size of API signatures being unnecessarily large. +code.descname { + font-size: 1em; +} + // Override center alignment in tables. td { text-align: left; diff --git a/doc/index.rst b/doc/index.rst index 8d55c7a1..b1e100af 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -131,7 +131,7 @@ The library produces compact per-call compiled code. For example compiles to just -.. code:: asm +.. code:: nasm main: # @main sub rsp, 24 diff --git a/doc/usage.rst b/doc/usage.rst index f9f81858..16ab864f 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -21,13 +21,13 @@ __ https://github.com/fmtlib/fmt/blob/master/CMakeLists.txt CMake works by generating native makefiles or project files that can be used in the compiler environment of your choice. The typical -workflow starts with:: +workflow starts with - mkdir build # Create a directory to hold the build output. +.. code:: sh + + mkdir build # Create a directory to hold the build output. cd build - cmake .. # Generate native build scripts. - -where :file:`{}` is a path to the ``fmt`` repository. + cmake .. # Generate native build scripts. If you are on a \*nix system, you should now see a Makefile in the current directory. Now you can build the library by running :command:`make`. @@ -146,7 +146,7 @@ system: Ubuntu doesn't package the ``clean-css`` plugin so you should use ``npm`` instead of ``apt`` to install both ``less`` and the plugin:: - sudo npm install -g less less-plugin-clean-css. + sudo npm install -g less less-plugin-clean-css First generate makefiles or project files using CMake as described in the previous section. Then compile the ``doc`` target/project, for example:: diff --git a/include/fmt/format.h b/include/fmt/format.h index 87b67948..7b3d9096 100644 --- a/include/fmt/format.h +++ b/include/fmt/format.h @@ -4126,7 +4126,7 @@ FMT_API auto vsystem_error(int error_code, string_view format_str, \rst Constructs :class:`std::system_error` with a message formatted with ``fmt::format(fmt, args...)``. - *error_code* is a system error code as given by ``errno``. + *error_code* is a system error code as given by ``errno``. **Example**::