From af211687a258cff8f0faccd865bc3cd464520ddc Mon Sep 17 00:00:00 2001
From: Manuel Weberndorfer <manuel.weberndorfer@id.ethz.ch>
Date: Mon, 9 Nov 2020 15:14:06 +0000
Subject: [PATCH] extract API documentation from cmdline docs

---
 cmdline/README.rst       | 29 +++++++++--------------------
 cmdline/src/README.rst   |  5 +++++
 docs/build_documentation |  5 +++--
 docs/index.rst           |  2 +-
 4 files changed, 18 insertions(+), 23 deletions(-)
 create mode 100644 cmdline/src/README.rst

diff --git a/cmdline/README.rst b/cmdline/README.rst
index 84e099b6..98b3d2cb 100644
--- a/cmdline/README.rst
+++ b/cmdline/README.rst
@@ -30,10 +30,8 @@ To use this library, you only need to familiarize yourself with a single class.
 This class is called ``CommandLineOptionParser``.
 It's in the namespace ``ae108::cmdline``.
 
-.. doxygenclass:: ae108::cmdline::CommandLineOptionParser
-
-Example Setup
-^^^^^^^^^^^^^
+Example Application
+^^^^^^^^^^^^^^^^^^^
 
 Let's try using this class in a simple example.
 
@@ -52,9 +50,6 @@ Construction
 ^^^^^^^^^^^^
 
 To parse the command line parameters, we'll construct a ``CommandLineOptionParser`` by providing a stream.
-
-.. doxygenfunction:: ae108::cmdline::CommandLineOptionParser::CommandLineOptionParser
-
 Let's say we want to print error messages and warnings to ``stderr``.
 
 .. code-block:: cpp
@@ -71,9 +66,9 @@ Adding Options
 
 The only thing that is missing are the options that we would like to parse.
 In this example, we are going greet the world if greetings are enabled via a command line flag.
-The ``CommandLineOptionParser`` class provides a ``withOption`` method to add flags.
+The ``CommandLineOptionParser`` class provides a ``withOption`` method that we are going to use to achieve that.
 
-In this example we'll add a flag ``--greet`` (with a short form ``-g``) together with a help text describing the flag.
+In this example we'll add a flag ``--enable_greeting`` (with a short form ``-g``) together with a help text describing the flag.
 
 .. code-block:: cpp
 
@@ -124,7 +119,7 @@ Example Source Code
 ^^^^^^^^^^^^^^^^^^^
 
 The full source code of the example is available in ``cmdline/examples/Example.cc``.
-If you want to build it and try it out, the executable target is called ``ae108-CmdLineExample``.
+If you want to build it and try it out, then compile the executable target ``ae108-CmdLineExample`` and run it with command line options of your choice.
 
 Outlook
 -------
@@ -141,16 +136,10 @@ For instance, it's possible to chain more than one call to ``withOption``:
 
 Also, there is another overload of ``withOption`` that permits to add flags without a help text.
 
-Interface Documentation
-^^^^^^^^^^^^^^^^^^^^^^^
-
-For reference, here's the documentation of the full interface of the ``CommandLineOptionParser`` class.
+You can find additional information in the API documentation of the library.
 
-.. doxygenclass:: ae108::cmdline::CommandLineOptionParser
-    :members:
+.. toctree::
 
-Tests
-^^^^^
+    cmdline-src.rst
 
-Finally, feel free to check out the tests in ``cmdline/test/CommandLineOptionParser_Test.cc``.
-They showcase the features of the library in many common use cases.
+In addition, the tests in ``cmdline/test/CommandLineOptionParser_Test.cc`` showcase the features in common use cases.
diff --git a/cmdline/src/README.rst b/cmdline/src/README.rst
new file mode 100644
index 00000000..8d08b1e6
--- /dev/null
+++ b/cmdline/src/README.rst
@@ -0,0 +1,5 @@
+CmdLine API Documentation
+=========================
+
+.. doxygenclass:: ae108::cmdline::CommandLineOptionParser
+    :members:
diff --git a/docs/build_documentation b/docs/build_documentation
index d2ebff73..a1912154 100755
--- a/docs/build_documentation
+++ b/docs/build_documentation
@@ -35,7 +35,7 @@ ROOT_DIRECTORY=$(readlink -e $(dirname "$0"))/..
 sphinx-quickstart \
     --no-batchfile \
     --sep \
-    -a "ETH Zurich, Mechanics and Materials Lab; California Institute of Technology" \
+    -a "ETH Zurich, California Institute of Technology" \
     -l "en" \
     -p "AE108" \
     -r "$(git describe)"
@@ -53,7 +53,8 @@ pandoc \
     -t rst \
     "$ROOT_DIRECTORY/README.md"
 cp "$ROOT_DIRECTORY/docs/index.rst" source/index.rst
-cp "$ROOT_DIRECTORY/cmdline/README.rst" source/Cmdline.rst
+cp "$ROOT_DIRECTORY/cmdline/README.rst" source/cmdline.rst
+cp "$ROOT_DIRECTORY/cmdline/src/README.rst" source/cmdline-src.rst
 
 make -j$(nproc) html
 make -j$(nproc) latexpdf
diff --git a/docs/index.rst b/docs/index.rst
index bb2df9f1..5ff3ece8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,4 +18,4 @@ Welcome to AE108!
 
 .. toctree::
     Getting Started <README.rst>
-    Cmdline.rst
+    cmdline.rst
-- 
GitLab