Update the nav bar and fix some doc bugs (libsemigroups#693)

Author: Joseph-Edwards

docs/Doxyfile

@@ -398,7 +398,7 @@ TOC_INCLUDE_HEADINGS   = 5
 # The default value is: DOXYGEN.
 # This tag requires that the tag MARKDOWN_SUPPORT is set to YES.
 
-MARKDOWN_ID_STYLE      = DOXYGEN
+MARKDOWN_ID_STYLE      = GITHUB
 
 # When enabled Doxygen tries to link words that correspond to documented
 # classes, or namespaces to their corresponding documentation. Such a link can
@@ -531,7 +531,7 @@ LOOKUP_CACHE_SIZE      = 0
 # DOT_NUM_THREADS setting.
 # Minimum value: 0, maximum value: 32, default value: 1.
 
-NUM_PROC_THREADS       = 8
+NUM_PROC_THREADS       = 0
 
 # If the TIMESTAMP tag is set different from NO then each generated page will
 # contain the date or date and time when the page was generated. Setting this to
@@ -1123,7 +1123,6 @@ EXCLUDE                = ../include/libsemigroups/detail/bruidhinn-traits.hpp \
                          ../include/libsemigroups/detail/multi-string-view.hpp \
                          ../include/libsemigroups/detail/path-iterators.hpp \
                          ../include/libsemigroups/detail/pool.hpp \
-                         ../include/libsemigroups/detail/report.hpp \
                          ../include/libsemigroups/detail/stl.hpp \ 
                          ../include/libsemigroups/detail/string.hpp \
                          ../include/libsemigroups/detail/timer.hpp \

docs/DoxygenLayout.xml

@@ -2,12 +2,11 @@
 
 ## Installing with conda
 
-This installation method assumes that you have anaconda or miniconda
-installed. See the [getting started](http://bit.ly/33B0Vfs) and
-[miniconda download page](https://conda.io/miniconda.html) on the
-[conda](https://conda.io/) website.
+This installation method assumes that you have a working version of `conda`.
+See the [getting started](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html)
+on the [conda](https://conda.io/) website.
 
-Activate the [conda-forge](https://conda-forge.github.io/) package
+Activate the [conda-forge](https://conda-forge.org/) package
 repository:
 
     conda config --add channels conda-forge
@@ -19,9 +18,9 @@ Install `libsemigroups`:
 ## From the sources
 
 Building `libsemigroups` from the source files requires a C++ compiler
-supporting the C++14 standard, `autoconf`, and `automake`. Building the
+supporting the C++17 standard, `autoconf`, and `automake`. Building the
 documentation from source has some additional requirements that are
-detailed [here](Building%20the%20documentation%20from%20source).
+detailed in the section [Building the documentation](index.md#building-the-documentation).
 
 ### From the github repo
 
@@ -35,51 +34,43 @@ To build `libsemigroups` from the github repository:
 
 To build `libsemigroups` from a release archive:
 
-::: parsed-literal
-curl -L -O
-<https://github.com/libsemigroups/libsemigroups/releases/latest/download/libsemigroups-%7Clibsemigroups-version>libsemigroups-versionlibsemigroups-versionlibsemigroups-version\|
-./configure && make -j8 && sudo make install
-:::
+    curl -L -O https://github.com/libsemigroups/libsemigroups/releases/latest/download/libsemigroups-3.0.0.tar.gz
+    tar -xf libsemigroups-3.0.0.tar.gz
+    rm -f libsemigroups-3.0.0.tar.gz
+    cd libsemigroups-3.0.0
+    ./configure && make -j8 && sudo make install
 
 ### Docker
 
-If you have [Docker](https://www.docker.com) installed, you can download
-an [x86 docker
-image](https://hub.docker.com/repository/docker/libsemigroups/libsemigroups-docker)
+If you have [Docker](https://www.docker.com) installed, you can download an
+[x86 docker image](https://hub.docker.com/repository/docker/libsemigroups/libsemigroups-docker)
 for `libsemigroups` as follows:
 
-::: parsed-literal
-docker pull libsemigroups/libsemigroups-docker
-:::
+    docker pull libsemigroups/libsemigroups-docker
 
-or an [arm docker
-image](https://hub.docker.com/repository/docker/libsemigroups/libsemigroups-docker-arm)
+or an [arm docker image](https://hub.docker.com/repository/docker/libsemigroups/libsemigroups-docker-arm)
 as follows
 
-::: parsed-literal
-docker pull libsemigroups/libsemigroups-docker-arm
-:::
+    docker pull libsemigroups/libsemigroups-docker-arm
 
 and run it by doing
 
-::: parsed-literal
-docker run \--rm -it libsemigroups/libsemigroups-docker docker run \--rm
--it libsemigroups/libsemigroups-docker-arm
-:::
+    docker run --rm -it libsemigroups/libsemigroups-docker
 
-If you want to use a specific version of `libsemigroups`, then use:
+or
 
-::: parsed-literal
-docker pull libsemigroups/libsemigroups-docker:version-1.0.9 docker run
-\--rm -it libsemigroups/libsemigroups-docker:version-1.0.9
-:::
+    docker run --rm -it libsemigroups/libsemigroups-docker-arm
+
+If you want to use a specific version of `libsemigroups`, such as 1.0.9, then
+use:
+
+    docker pull libsemigroups/libsemigroups-docker:version-1.0.9
+    docker run --rm -it libsemigroups/libsemigroups-docker:version-1.0.9
 
 or, for the latest version, use:
 
-::: parsed-literal
-docker pull libsemigroups/libsemigroups-docker:latest docker run \--rm
--it libsemigroups/libsemigroups-docker:latest
-:::
+    docker pull libsemigroups/libsemigroups-docker:latest
+    docker run --rm -it libsemigroups/libsemigroups-docker:latest
 
 ## Configuration options
 
@@ -96,13 +87,12 @@ configuration options are available for `libsemigroups`:
 | \--with-external-fmt       | do not use the included copy of fmt (default=no)   |
 | \--with-external-eigen     | do not use the included copy of eigen (default=no) |
 | \--disable-popcnt          | do not use \_\_builtin_popcountl (default=yes)     |
-| \--disable-clzll           | do not use \_\_builtin_ctzll (default=yes)         |
+| \--disable-clzll           | do not use \_\_builtin_clzll (default=yes)         |
 
-Debug mode and verbose mode significantly degrade the performance of
-`libsemigroups`. Compiling with `fmt` enabled increases build times
-significantly. Note that the flags `--enable-fmt` and
-`--with-external-fmt` are independent of each other, and so both flags
-should be included to enable `fmt` and use an external `fmt`.
+Debug mode significantly degrades the performance of `libsemigroups`. Note that
+the flags `--enable-eigen` and `--with-external-eigen` are independent of each
+other, and so both flags should be included to enable `eigen` and use an
+external `eigen`.
 
 ## Make install
 
@@ -128,28 +118,19 @@ above then
     PKG_CONFIG_PATH=/foo/bar/lib/pkgconfig pkg-config --modversion libsemigroups
 
 will print the version of the installed `libsemigroups`. (As usual,
-`PKG_CONFIG_PATH` may be exported, added to shell configuration, etc.)
+`PKG_CONFIG_PATH` may be exported, added to shell configuration, etc.).
 
 ## Building the documentation
 
-The following are required to be able to build the documentation:
-
-1.  `python3`
-2.  `doxygen`
-3.  the python packages:
-    `sphinx bs4 lxml breathe pyyaml sphinx_rtd_theme sphinx_copybutton sphinxcontrib-bibtex`
-
-Assuming you already have `python3` install, on Mac OSX you can install
-all of the above by doing:
-
-    brew install doxygen sphinx
-    pip3 install -r docs/requirements.txt
+To build the documentation, a version of `doxygen` is required. Instructions on
+how to do this can be found on Doxygen's
+[Installation page](https://www.doxygen.nl/manual/install.html).
 
-Then it ought to be possible to just run `make doc` in the
-`libsemigroups` directory.
+Then, it ought to be possible to just run `make doc` in the
+`libsemigroups` directory, and the documentation will be generated.
 
 ## Issues
 
 If you find any problems with `libsemigroups`, or have any suggestions
-for features that you'd like to see, please use the [issue
-tracker](https://github.com/libsemigroups/libsemigroups/issues).
+for features that you'd like to see, please use the
+[issue tracker](https://github.com/libsemigroups/libsemigroups/issues).

docs/install.md

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Check for bad linebreaks within doxygen commands.
+
+The script should be run from the libsemigroups root directory. It searches
+every .hpp file in the libsemigroups directory for doxygen-style documentation 
+lines that end with one of the following:
+    * \\ref
+    * \\c
+    * \\p
+    * \\copydoc
+"""
+import re
+from glob import iglob
+
+BOLD_TEXT = "\033[1m"
+YELLOW = "\033[93m"
+END_COLOUR = "\033[0m"
+
+command_with_line_break = re.compile(
+    r"//!.*((?:\\ref)|(?:\\c)|(?:\\p)(?:\\copydoc))(\s+)?$",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+globs = ["include/libsemigroups/*.hpp", "include/libsemigroups/detail*.hpp"]
+
+
+def process_file(filename):
+    """Check for doxygen commands that contain line breaks in the specified
+    file.
+    """
+    with open(filename, "r") as f:
+        check_doc = True
+        for line_no, line in enumerate(f):
+            if check_doc and "/*" in line:
+                check_doc = False
+            if not check_doc and "*/" in line:
+                check_doc = True
+            if not check_doc:
+                continue
+
+            command_match = command_with_line_break.search(line)
+            if command_match:
+                command = command_match[1]
+                print(
+                    f"{YELLOW}warning: {command} appears at the end of the "
+                    f"line at {filename}:{line_no + 1}{END_COLOUR}"
+                )
+
+
+def process_path(pathname):
+    """Check for doxygen commands that contain line breaks for all files a
+    specified path.
+    """
+    print(
+        BOLD_TEXT
+        + f"Checking for for bad linebreaks in {pathname} . . ."
+        + END_COLOUR
+    )
+    for filename in iglob(pathname, include_hidden=True):
+        process_file(filename)
+    print(f"{BOLD_TEXT}Done{END_COLOUR}")
+
+
+if __name__ == "__main__":
+    for pathname in globs:
+        process_path(pathname)

etc/check_doxygen_line_breaks.py

@@ -2,7 +2,7 @@
 set -e
 
 echo "Checking whether to build the to-table . . ."
-if command -v pdflatex && command -v ghostscript 2>&1 >/dev/null; then
+if command -v pdflatex && command -v inkscape 2>&1 >/dev/null; then
     cd docs/pictures
     echo "Building to-table . . ."
     pdflatex -shell-escape to-table.tex
@@ -12,6 +12,8 @@ else
 fi
 echo "Checking doc order . . ."
 ./etc/check_doc_order.py
+echo "Checking doxygen linebreaks . . ."
+./etc/check_doxygen_line_breaks.py
 mkdir -p docs/build
 cd docs/
 echo "doxygen --version"

etc/make-doc.sh

@@ -237,9 +237,10 @@ namespace libsemigroups {
     //!
     //! The type of the action of elements of type `Element` on points of type
     //! `Point`. This type should be a stateless trivially default constructible
-    //! class with a call operator of signature `void(Point&, Point const&,
-    //! Element const&)` which computes the action of its 3rd argument on its
-    //! 2nd argument, and stores it in its 1st argument.
+    //! class with a call operator of signature
+    //! `void(Point&, Point const&, Element const&)` which computes the action
+    //! of its 3rd argument on its 2nd argument, and stores it in its 1st
+    //! argument.
     //!
     //! \sa ImageRightAction, ImageLeftAction
     using action_type = Func;
@@ -690,8 +691,8 @@ namespace libsemigroups {
     //!
     //! Returns an element \c x of the semigroup generated by the generators
     //! in the action such that if \c r is the root of the strongly connected
-    //! component containing \c at(pos), then after `Func()(res, r,
-    //! x)` the point \c res equals \c at(pos).
+    //! component containing \c at(pos), then after
+    //! `Func()(res, r, x)` the point \c res equals \c at(pos).
     //!
     //! \param pos a position in the action.
     //!