From 4f7df299ea78201fcbce2d595bb5d9805082f804 Mon Sep 17 00:00:00 2001
From: Victor Zverovich <victor.zverovich@gmail.com>
Date: Sun, 8 Nov 2020 05:40:39 -0800
Subject: [PATCH] Improve docs

---
 doc/api.rst           | 24 +++++++++++++-----------
 include/fmt/color.h   |  6 +++++-
 support/build-docs.py | 15 ++++-----------
 3 files changed, 22 insertions(+), 23 deletions(-)

diff --git a/doc/api.rst b/doc/api.rst
index 72698cde..c3d47dfd 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -412,24 +412,26 @@ Date and Time Formatting
   <https://en.cppreference.com/w/cpp/chrono/time_point>`_
 * `std::tm <https://en.cppreference.com/w/cpp/chrono/c/tm>`_
 
-For example::
+The format syntax is described in :ref:`chrono-specs`.
+
+**Example**::
 
   #include <fmt/chrono.h>
 
-  std::time_t t = std::time(nullptr);
+  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));
+    // Prints "The date is 2020-11-07." (with the current date):
+    fmt::print("The date is {:%Y-%m-%d}.", fmt::localtime(t));
 
-  using namespace std::literals::chrono_literals;
+    using namespace std::literals::chrono_literals;
 
-  // Prints "Default format: 42s 100ms":
-  fmt::print("Default format: {} {}\n", 42s, 100ms);
+    // Prints "Default format: 42s 100ms":
+    fmt::print("Default format: {} {}\n", 42s, 100ms);
 
-  // Prints "strftime-like format: 03:15:30":
-  fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s);
-
-The syntax is described in :ref:`chrono-specs`.
+    // Prints "strftime-like format: 03:15:30":
+    fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s);
+  }
 
 .. doxygenfunction:: localtime(std::time_t)
 
diff --git a/include/fmt/color.h b/include/fmt/color.h
index 94e3419d..b476ff52 100644
--- a/include/fmt/color.h
+++ b/include/fmt/color.h
@@ -523,11 +523,15 @@ void print(std::FILE* f, const text_style& ts, const S& format_str,
 }
 
 /**
+  \rst
   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);
+  \endrst
  */
 template <typename S, typename... Args,
           FMT_ENABLE_IF(detail::is_string<S>::value)>
diff --git a/support/build-docs.py b/support/build-docs.py
index e3d739ef..ade98dd4 100755
--- a/support/build-docs.py
+++ b/support/build-docs.py
@@ -3,7 +3,7 @@
 
 from __future__ import print_function
 import errno, os, shutil, subprocess, sys, urllib
-from subprocess import call, check_call, Popen, PIPE, STDOUT
+from subprocess import check_call, Popen, PIPE, STDOUT
 
 def rmtree_if_exists(dir):
     try:
@@ -12,23 +12,16 @@ def rmtree_if_exists(dir):
         if e.errno == errno.ENOENT:
             pass
 
-def install_dependencies():
-    deb_file = 'doxygen_1.8.6-2_amd64.deb'
-    urllib.urlretrieve('http://mirrors.kernel.org/ubuntu/pool/main/d/doxygen/' +
-                       deb_file, deb_file)
-    check_call(['sudo', 'dpkg', '-i', deb_file])
-
+# Build the docs.
 fmt_dir = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
-
-is_ci = 'CI' in os.environ
-if is_ci:
-    install_dependencies()
 sys.path.insert(0, os.path.join(fmt_dir, 'doc'))
 import build
 build.create_build_env()
 html_dir = build.build_docs()
+
 repo = 'fmtlib.github.io'
 branch = os.environ['GITHUB_REF']
+is_ci = 'CI' in os.environ
 if is_ci and branch != 'refs/heads/master':
     print('Branch: ' + branch)
     exit(0) # Ignore non-master branches