Migrate to mkdocs

doc/api.md

@@ -41,10 +41,10 @@ in Python. 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]{.title-ref} is a format string
+in the resulting string. [`fmt::format_string`](#format_string) is a format 
-which can be implicitly constructed from a string literal or a `constexpr`
+string which can be implicitly constructed from a string literal or a
-string and is checked at compile time in C++20. To pass a runtime format
+`constexpr` string and is checked at compile time in C++20. To pass a runtime
-string wrap it in [fmt::runtime]{.title-ref}.
+format string wrap it in [fmt::runtime](#runtime).
 
 *args* is an argument list representing objects to be formatted.
 
@@ -52,7 +52,6 @@ I/O errors are reported as [`std::system_error`](
 https://en.cppreference.com/w/cpp/error/system_error) exceptions unless
 specified otherwise.
 
-<a id="print"></a>
 ::: print(format_string<T...>, T&&...)
 
 ::: print(FILE*, format_string<T...>, T&&...)
@@ -100,7 +99,7 @@ Example ([run](https://godbolt.org/z/nvME4arz8)):
     }
 
     int main() {
-      fmt::print("{}\n", kevin_namespacy::film::se7en); // prints "7"
+      fmt::print("{}\n", kevin_namespacy::film::se7en); // Output: 7
     }
 
 Using specialization is more complex but gives you full control over
@@ -154,7 +153,7 @@ fmt::format("{:>10}", color::blue)
 
 will return `"      blue"`.
 
-The experimental `nested_formatter` provides an easy way of applying a
+<!-- The experimental `nested_formatter` provides an easy way of applying a
 formatter to one or more subobjects.
 
 For example:
@@ -185,7 +184,7 @@ prints:
 
 Notice that fill, align and width are applied to the whole object which
 is the recommended behavior while the remaining specifiers apply to
-elements.
+elements. -->
 
 In general the formatter has the following form:
 
@@ -232,10 +231,10 @@ struct B : A {
 };
 
 template <typename T>
-struct fmt::formatter<T, std::enable_if_t<std::is_base_of<A, T>::value, char>> :
+struct fmt::formatter<T, std::enable_if_t<std::is_base_of_v<A, T>, char>> :
     fmt::formatter<std::string> {
   auto format(const A& a, format_context& ctx) const {
-    return fmt::formatter<std::string>::format(a.name(), ctx);
+    return formatter<std::string>::format(a.name(), ctx);
   }
 };
 ```
@@ -248,12 +247,18 @@ struct fmt::formatter<T, std::enable_if_t<std::is_base_of<A, T>::value, char>> :
 int main() {
   B b;
   A& a = b;
-  fmt::print("{}", a); // prints "B"
+  fmt::print("{}", a); // Output: B
 }
 ```
 
-Providing both a `formatter` specialization and a `format_as` overload
+Providing both a `formatter` specialization and a `format_as` overload is
-is disallowed.
+disallowed.
+
+::: basic_format_parse_context
+
+::: context
+
+::: format_context
 
 ### Compile-Time Format String Checks
 
@@ -311,12 +316,6 @@ parameterized version.
 
 ::: basic_format_arg
 
-::: basic_format_parse_context
-
-::: context
-
-::: format_context
-
 ### Compatibility
 
 ::: basic_string_view
@@ -368,7 +367,7 @@ The following user-defined literals are defined in `fmt/format.h`.
 
 The {fmt} library supports custom dynamic memory allocators. A custom
 allocator class can be specified as a template argument to
-`fmt::basic_memory_buffer`{.interpreted-text role="class"}:
+[`fmt::basic_memory_buffer`](#basic_memory_buffer):
 
     using custom_memory_buffer = 
       fmt::basic_memory_buffer<char, fmt::inline_buffer_size, custom_allocator>;
@@ -439,18 +438,16 @@ The library also supports convenient formatting of ranges and tuples:
 
     #include <fmt/ranges.h>
 
-    std::tuple<char, int, float> t{'a', 1, 2.0f};
+    fmt::print("{}", std::tuple<char, int>{'a', 42});
-    // Prints "('a', 1, 2.0)"
+    // Output: ('a', 42)
-    fmt::print("{}", t);
 
-Using `fmt::join`, you can separate tuple elements with a custom
+Using `fmt::join`, you can separate tuple elements with a custom separator:
-separator:
 
     #include <fmt/ranges.h>
 
-    std::tuple<int, char> t = {1, 'a'};
+    auto t = std::tuple<int, char>{1, 'a'};
-    // Prints "1, a"
     fmt::print("{}", fmt::join(t, ", "));
+    // Output: 1, a
 
 ::: join(Range&&, string_view)
 
@@ -475,16 +472,17 @@ chrono-format-specifications).
     int main() {
       std::time_t t = std::time(nullptr);
 
-      // Prints "The date is 2020-11-07." (with the current date):
       fmt::print("The date is {:%Y-%m-%d}.", fmt::localtime(t));
+      // Output: The date is 2020-11-07.
+      // (with 2020-11-07 replaced by the current date)
 
       using namespace std::literals::chrono_literals;
 
-      // Prints "Default format: 42s 100ms":
       fmt::print("Default format: {} {}\n", 42s, 100ms);
+      // Output: Default format: 42s 100ms
 
-      // Prints "strftime-like format: 03:15:30":
       fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s);
+      // Output: strftime-like format: 03:15:30
     }
 
 ::: localtime(std::time_t)

include/fmt/args.h

@@ -159,7 +159,7 @@ class dynamic_format_arg_store
     Note that custom types and string types (but not string views) are copied
     into the store dynamically allocating memory if necessary.
 
-    **Example**::
+    **Example**:
 
       fmt::dynamic_format_arg_store<fmt::format_context> store;
       store.push_back(42);
@@ -180,7 +180,7 @@ class dynamic_format_arg_store
     Adds a reference to the argument into the dynamic store for later passing to
     a formatting function.
 
-    **Example**::
+    **Example**:
 
       fmt::dynamic_format_arg_store<fmt::format_context> store;
       char band[] = "Rolling Stones";

include/fmt/color.h

@@ -478,7 +478,7 @@ inline void vprint(FILE* f, const text_style& ts, string_view fmt,
   Formats a string and prints it to the specified file stream using ANSI
   escape sequences to specify text formatting.
 
-  **Example**::
+  **Example**:
 
     fmt::print(fmt::emphasis::bold | fg(fmt::color::red),
                "Elapsed time: {0:.2f} seconds", 1.23);
@@ -495,7 +495,7 @@ void print(FILE* f, const text_style& ts, format_string<T...> fmt,
   Formats a string and prints it to stdout using ANSI escape sequences to
   specify text formatting.
 
-  **Example**::
+  **Example**:
 
     fmt::print(fmt::emphasis::bold | fg(fmt::color::red),
                "Elapsed time: {0:.2f} seconds", 1.23);
@@ -518,7 +518,7 @@ inline auto vformat(const text_style& ts, string_view fmt, format_args args)
   Formats arguments and returns the result as a string using ANSI
   escape sequences to specify text formatting.
 
-  **Example**::
+  **Example**:
 
     #include <fmt/color.h>
     std::string message = fmt::format(fmt::emphasis::bold | fg(fmt::color::red),
@@ -548,7 +548,7 @@ auto vformat_to(OutputIt out, const text_style& ts, string_view fmt,
   Formats arguments with the given text_style, writes the result to the output
   iterator ``out`` and returns the iterator past the end of the output range.
 
-  **Example**::
+  **Example**:
 
     std::vector<char> out;
     fmt::format_to(std::back_inserter(out),
@@ -603,7 +603,7 @@ struct formatter<detail::styled_arg<T>, Char> : formatter<T, Char> {
   Returns an argument that will be formatted using ANSI escape sequences,
   to be used in a formatting function.
 
-  **Example**::
+  **Example**:
 
     fmt::print("Elapsed time: {0:.2f} seconds",
                fmt::styled(1.23, fmt::fg(fmt::color::green) |

include/fmt/compile.h

@@ -34,7 +34,7 @@ struct is_compiled_string : std::is_base_of<compiled_string, S> {};
  * compile time and converted into efficient formatting code. Requires C++17
  * `constexpr if` compiler support.
  *
- * **Example**::
+ * **Example**:
  *
  *     // Converts 42 into std::string using the most efficient method and no
  *     // runtime format string processing.

include/fmt/format.h

@@ -817,7 +817,7 @@ enum { inline_buffer_size = 500 };
  * types with the first `SIZE` elements stored in the object itself. Most
  * commonly used via the `memory_buffer` alias for `char`.
  *
- * **Example**::
+ * **Example**:
  *
  *     auto out = fmt::memory_buffer();
  *     fmt::format_to(std::back_inserter(out), "The answer is {}.", 42);
@@ -1812,7 +1812,7 @@ inline auto find_escape(const char* begin, const char* end)
 /**
  * Constructs a compile-time format string from a string literal `s`.
  *
- * **Example**::
+ * **Example**:
  *
  *     // A compile-time error because 'd' is an invalid specifier for strings.
  *     std::string s = fmt::format(FMT_STRING("{:d}"), "foo");
@@ -3873,7 +3873,7 @@ FMT_API auto vsystem_error(int error_code, string_view format_str,
  * `fmt::format(fmt, args...)`.
  * `error_code` is a system error code as given by `errno`.
  *
- * **Example**::
+ * **Example**:
  *
  *     // This throws std::system_error with the description
  *     //   cannot open file 'madeup': No such file or directory
@@ -3890,20 +3890,17 @@ auto system_error(int error_code, format_string<T...> fmt, T&&... args)
 }
 
 /**
-  \rst
+ * Formats an error message for an error returned by an operating system or a
-  Formats an error message for an error returned by an operating system or a
+ * language runtime, for example a file opening error, and writes it to `out`.
-  language runtime, for example a file opening error, and writes it to `out`.
+ * The format is the same as the one used by `std::system_error(ec, message)`
-  The format is the same as the one used by ``std::system_error(ec, message)``
+ * where `ec` is `std::error_code(error_code, std::generic_category())`.
-  where ``ec`` is ``std::error_code(error_code, std::generic_category()})``.
+ * It is implementation-defined but normally looks like:
-  It is implementation-defined but normally looks like:
+ *
-
+ *     <message>: <system-message>
-  .. parsed-literal::
+ *
-     *<message>*: *<system-message>*
+ * where `<message>` is the passed message and `<system-message>` is the system
-
+ * message corresponding to the error code.
-  where *<message>* is the passed message and *<system-message>* is the system
+ * `error_code` is a system error code as given by `errno`.
-  message corresponding to the error code.
-  `error_code` is a system error code as given by ``errno``.
-  \endrst
  */
 FMT_API void format_system_error(detail::buffer<char>& out, int error_code,
                                  const char* message) noexcept;
@@ -3912,7 +3909,7 @@ FMT_API void format_system_error(detail::buffer<char>& out, int error_code,
 // Can be used to report errors from destructors.
 FMT_API void report_system_error(int error_code, const char* message) noexcept;
 
-/** Fast integer formatter. */
+/// A fast integer formatter.
 class format_int {
  private:
   // Buffer should be large enough to hold all digits (digits10 + 1),
@@ -3944,31 +3941,23 @@ class format_int {
   explicit format_int(unsigned long long value)
       : str_(format_unsigned(value)) {}
 
-  /** Returns the number of characters written to the output buffer. */
+  /// Returns the number of characters written to the output buffer.
   auto size() const -> size_t {
     return detail::to_unsigned(buffer_ - str_ + buffer_size - 1);
   }
 
-  /**
+  /// Returns a pointer to the output buffer content. No terminating null
-    Returns a pointer to the output buffer content. No terminating null
+  /// character is appended.
-    character is appended.
-   */
   auto data() const -> const char* { return str_; }
 
-  /**
+  /// Returns a pointer to the output buffer content with terminating null
-    Returns a pointer to the output buffer content with terminating null
+  /// character appended.
-    character appended.
-   */
   auto c_str() const -> const char* {
     buffer_[buffer_size - 1] = '\0';
     return str_;
   }
 
-  /**
+  /// Returns the content of the output buffer as an `std::string`.
-    \rst
-    Returns the content of the output buffer as an ``std::string``.
-    \endrst
-   */
   auto str() const -> std::string { return std::string(str_, size()); }
 };
 
@@ -4008,7 +3997,7 @@ struct formatter<Char[N], Char> : formatter<basic_string_view<Char>, Char> {};
 /**
  * Converts `p` to `const void*` for pointer formatting.
  *
- * **Example**::
+ * **Example**:
  *
  *     auto s = fmt::format("{}", fmt::ptr(p));
  */
@@ -4020,7 +4009,7 @@ template <typename T> auto ptr(T p) -> const void* {
 /**
  * Converts `e` to the underlying type.
  *
- * **Example**::
+ * **Example**:
  *
  *     enum class color { red, green, blue };
  *     auto s = fmt::format("{}", fmt::underlying(color::red));
@@ -4074,15 +4063,13 @@ template <typename T> struct group_digits_view {
 };
 
 /**
-  \rst
+ * Returns a view that formats an integer value using ',' as a
-  Returns a view that formats an integer value using ',' as a locale-independent
+ * locale-independent thousands separator.
-  thousands separator.
+ *
-
+ * **Example**:
-  **Example**::
+ *
-
+ *     fmt::print("{}", fmt::group_digits(12345));
-    fmt::print("{}", fmt::group_digits(12345));
+ *     // Output: "12,345"
-    // Output: "12,345"
-  \endrst
  */
 template <typename T> auto group_digits(T value) -> group_digits_view<T> {
   return {value};
@@ -4175,7 +4162,7 @@ template <typename T, typename Char = char> struct nested_formatter {
 /**
  * Converts `value` to `std::string` using the default format for type `T`.
  *
- * **Example**::
+ * **Example**:
  *
  *     std::string answer = fmt::to_string(42);
  */
@@ -4326,14 +4313,12 @@ struct formatter<detail::float128, Char>
 #if FMT_USE_USER_DEFINED_LITERALS
 inline namespace literals {
 /**
-  \rst
+ * User-defined literal equivalent of `fmt::arg`.
-  User-defined literal equivalent of :func:`fmt::arg`.
+ *
-
+ * **Example**:
-  **Example**::
+ *
-
+ *     using namespace fmt::literals;
-    using namespace fmt::literals;
+ *     fmt::print("Elapsed time: {s:.2f} seconds", "s"_a=1.23);
-    fmt::print("Elapsed time: {s:.2f} seconds", "s"_a=1.23);
-  \endrst
  */
 #  if FMT_USE_NONTYPE_TEMPLATE_ARGS
 template <detail_exported::fixed_string Str> constexpr auto operator""_a() {
@@ -4354,9 +4339,9 @@ FMT_API auto vformat(string_view fmt, format_args args) -> std::string;
  * Formats `args` according to specifications in `fmt` and returns the result
  * as a string.
  *
- * **Example**::
+ * **Example**:
  *
- *     #include <fmt/core.h>
+ *     #include <fmt/format.h>
  *     std::string message = fmt::format("The answer is {}.", 42);
 */
 template <typename... T>

include/fmt/os.h

@@ -150,7 +150,7 @@ FMT_API std::system_error vwindows_error(int error_code, string_view format_str,
  If `error_code` is not a valid error code such as -1, the system message
  will look like "error -1".
 
- **Example**::
+ **Example**:
 
    // This throws a system_error with the description
    //   cannot open file 'madeup': The system cannot find the file specified.
@@ -444,7 +444,7 @@ class FMT_API ostream {
     (``file::WRONLY | file::CREATE | file::TRUNC`` by default)
   * ``buffer_size=<integer>``: Output buffer size
 
-  **Example**::
+  **Example**:
 
     auto out = fmt::output_file("guide.txt");
     out.print("Don't {}", "Panic");

include/fmt/ostream.h

@@ -139,7 +139,7 @@ struct formatter<detail::streamed_view<T>, Char>
   \rst
   Returns a view that formats `value` via an ostream ``operator<<``.
 
-  **Example**::
+  **Example**:
 
     fmt::print("Current thread id: {}\n",
                fmt::streamed(std::this_thread::get_id()));
@@ -175,7 +175,7 @@ void vprint(std::basic_ostream<Char>& os,
   \rst
   Prints formatted data to the stream `os`.
 
-  **Example**::
+  **Example**:
 
     fmt::print(cerr, "Don't {}!", "panic");
   \endrst

include/fmt/printf.h

@@ -602,7 +602,7 @@ inline auto vsprintf(basic_string_view<Char> fmt,
   \rst
   Formats arguments and returns the result as a string.
 
-  **Example**::
+  **Example**:
 
     std::string message = fmt::sprintf("The answer is %d", 42);
   \endrst
@@ -628,7 +628,7 @@ inline auto vfprintf(std::FILE* f, basic_string_view<Char> fmt,
   \rst
   Prints formatted data to the file `f`.
 
-  **Example**::
+  **Example**:
 
     fmt::fprintf(stderr, "Don't %s!", "panic");
   \endrst
@@ -650,7 +650,7 @@ FMT_DEPRECATED inline auto vprintf(basic_string_view<Char> fmt,
   \rst
   Prints formatted data to ``stdout``.
 
-  **Example**::
+  **Example**:
 
     fmt::printf("Elapsed time: %.2f seconds", 1.23);
   \endrst

include/fmt/ranges.h

@@ -658,30 +658,26 @@ struct formatter<join_view<It, Sentinel, Char>, Char> {
   }
 };
 
-/**
+/// Returns a view that formats the iterator range `[begin, end)` with elements
-  Returns a view that formats the iterator range `[begin, end)` with elements
+/// separated by `sep`.
-  separated by `sep`.
- */
 template <typename It, typename Sentinel>
 auto join(It begin, Sentinel end, string_view sep) -> join_view<It, Sentinel> {
   return {std::move(begin), end, sep};
 }
 
 /**
-  \rst
+ * Returns a view that formats `range` with elements separated by `sep`.
-  Returns a view that formats `range` with elements separated by `sep`.
+ *
-
+ *  **Example**:
-  **Example**::
+ *
-
+ *     std::vector<int> v = {1, 2, 3};
-    std::vector<int> v = {1, 2, 3};
+ *     fmt::print("{}", fmt::join(v, ", "));
-    fmt::print("{}", fmt::join(v, ", "));
+ *     // Output: 1, 2, 3
-    // Output: "1, 2, 3"
+ *
-
+ * `fmt::join` applies passed format specifiers to the range elements:
-  ``fmt::join`` applies passed format specifiers to the range elements::
+ *
-
+ *     fmt::print("{:02}", fmt::join(v, ", "));
-    fmt::print("{:02}", fmt::join(v, ", "));
+ *     // Output: 01, 02, 03
-    // Output: "01, 02, 03"
-  \endrst
  */
 template <typename Range>
 auto join(Range&& r, string_view sep)
@@ -809,7 +805,7 @@ FMT_BEGIN_EXPORT
   \rst
   Returns an object that formats `tuple` with elements separated by `sep`.
 
-  **Example**::
+  **Example**:
 
     std::tuple<int, char> t = {1, 'a'};
     fmt::print("{}", fmt::join(t, ", "));
@@ -827,7 +823,7 @@ FMT_CONSTEXPR auto join(const std::tuple<T...>& tuple, string_view sep)
   Returns an object that formats `initializer_list` with elements separated by
   `sep`.
 
-  **Example**::
+  **Example**:
 
     fmt::print("{}", fmt::join({1, 2, 3}, ", "));
     // Output: "1, 2, 3"