Documentation fixes

.readthedocs.yaml

@@ -13,6 +13,7 @@ build:
   jobs:
     pre_build:
       - doxygen
+      - cd doc && python make_md.py
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

Doxyfile

@@ -155,7 +155,7 @@ ALWAYS_DETAILED_SEC    = NO
 # operators of the base classes will not be shown.
 # The default value is: NO.
 
-INLINE_INHERITED_MEMB  = YES
+INLINE_INHERITED_MEMB  = NO
 
 # If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path
 # before files name in the file list and in the header files. If set to NO the
@@ -380,7 +380,7 @@ AUTOLINK_SUPPORT       = YES
 # diagrams that involve STL classes more complete and accurate.
 # The default value is: NO.
 
-BUILTIN_STL_SUPPORT    = NO
+BUILTIN_STL_SUPPORT    = YES
 
 # If you use Microsoft's C++/CLI language, you should set this option to YES to
 # enable parsing support.
@@ -540,7 +540,7 @@ EXTRACT_STATIC         = YES
 # for Java sources.
 # The default value is: YES.
 
-EXTRACT_LOCAL_CLASSES  = NO
+EXTRACT_LOCAL_CLASSES  = YES
 
 # This flag is only useful for Objective-C code. If set to YES, local methods,
 # which are defined in the implementation section but not in the interface are
@@ -588,7 +588,7 @@ HIDE_UNDOC_CLASSES     = NO
 # documentation.
 # The default value is: NO.
 
-HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_FRIEND_COMPOUNDS  = YES
 
 # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
 # documentation blocks found inside the body of a function. If set to NO, these
@@ -691,7 +691,7 @@ SORT_BRIEF_DOCS        = NO
 # detailed member documentation.
 # The default value is: NO.
 
-SORT_MEMBERS_CTORS_1ST = NO
+SORT_MEMBERS_CTORS_1ST = YES
 
 # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
 # of group names into alphabetical order. If set to NO the group names will
@@ -921,7 +921,7 @@ WARN_LINE_FORMAT       = "at line $line of file $file"
 # specified the warning and error messages are written to standard output
 # (stdout).
 
-WARN_LOGFILE           =
+WARN_LOGFILE           = doxygen_warnings.txt
 
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
@@ -1020,7 +1020,12 @@ EXCLUDE_PATTERNS       = */demos/* \
 # ANamespace::AClass, ANamespace::*Test
 
 EXCLUDE_SYMBOLS        = EMP_* \
-                         EM_*
+                         EM_*  \
+                         internal \
+                         detail \
+                         decltypedetail \
+                         __*
+
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include
@@ -1072,7 +1077,7 @@ IMAGE_PATH             =
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by doxygen.
 
-INPUT_FILTER           =
+INPUT_FILTER           = doc/filter_namespace
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 # basis. Doxygen will compare the file name with each pattern and apply the
@@ -2535,7 +2540,7 @@ INCLUDE_GRAPH          = YES
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INCLUDED_BY_GRAPH      = YES
+INCLUDED_BY_GRAPH      = NO
 
 # If the CALL_GRAPH tag is set to YES then doxygen will generate a call
 # dependency graph for every global function or class method.

Makefile

@@ -46,6 +46,7 @@ test-cookiecutter: ../cookiecutter-empirical-project
 
 doc:
 	doxygen
+	cd doc && python make_md.py
 	cd doc && make html coverage
 
 coverage:

doc/QuickStartGuides/todos/todo.md

@@ -1,7 +1,7 @@
 # Work In Progress
 
 The following pages are a work in progress 🚧.
-[Contributions](contribution-guidelines-and-review) are welcome!
+[Contributions](../../dev/contribution-guidelines-and-review) are welcome!
 
 ```{toctree}
 X-CreateWorld

doc/conf.py

@@ -41,6 +41,7 @@
     'sphinx_rtd_theme',
     'breathe',
     'myst_parser',
+    'sphinx_tippy'
 ]
 
 myst_heading_anchors = 4

doc/filter_namespace

@@ -0,0 +1,28 @@
+#!/usr/bin/python3
+
+import sys
+
+with open(sys.argv[1]) as infile:
+    open_braces = 0
+    namespace_removed = 0
+    for line in infile:
+        line = line.strip()
+        if line.startswith("namespace emp {") or \
+           line.startswith("namespace web {") or \
+           line.startswith("namespace prefab {") or \
+           line.startswith("namespace emp::prefab {") or \
+           line.startswith("namespace evo {"):
+            namespace_removed += 1
+            open_braces = 1
+            print()
+        elif namespace_removed and line == "}":
+            print()
+            namespace_removed -= 1
+        else:
+            if namespace_removed:
+                open_braces += line.count("{")
+                open_braces -= line.count("}")
+            line = line.replace("emp::", "")
+            line = line.replace("web::", "")
+            line = line.replace("prefab::", "")
+            print(line)

doc/library/base/base.md

@@ -39,13 +39,12 @@ emp::array<int, 3> array({1,2,3});
 ## Empirical asserts
 
 These asserts function similarly to normal asserts, with a few important
-additional features: - If compiled with Emscripten they will provide
-pop-up alerts when run in a web browser. - emp_assert can take
-additional arguments. If the assert is triggered, those extra arguments
-will be evaluated and printed. - if NDEBUG -or- EMP_NDEBUG is defined,
-the expression in emp_assert() is not evaluated. - if EMP_TDEBUG is
-defined, emp_assert() goes into test mode and records failures, but
-does not abort. (useful for unit tests of asserts)
+additional features:
+
+- If compiled with Emscripten they will provide pop-up alerts when run in a web browser.
+- emp_assert can take additional arguments. If the assert is triggered, those extra arguments will be evaluated and printed.
+- if NDEBUG **or** EMP_NDEBUG is defined, the expression in emp_assert() is not evaluated.
+- if EMP_TDEBUG is defined, emp_assert() goes into test mode and records failures, but does not abort. (useful for unit tests of asserts)
 
 Example:
 
@@ -59,20 +58,41 @@ emp_assert(a==5, a);
 When compiled in debug mode (i.e. without the -DNDEBUG flag), this will
 trigger an assertion error and print the value of a.
 
-### emp_assert API (base/assert.hpp)
+Empirical also has an emscripten-specific assert, which will only trigger an error when the code was compiled with Emscripten:
+
+```cpp
+#include "Empirical/include/emp/base/emscripten_assert.hpp"
+
+int a = 6;
+// If compiled in with emscripten in debug mode,
+// this will print a warning and the value of a
+emp_emscripten_assert(a==5, a);
 
-```{eval-rst}
-.. doxygendefine:: emp_assert
-  :project: Empirical
-  :no-link:   
 ```
 
-```{eval-rst}
-.. doxygendefine:: emp_emscripten_assert
-  :project: Empirical
-  :no-link:   
+If you want your assert to be triggered outside of debug mode, you can use {c:func}`emp_always_assert`.
+
+## Empirical Warnings
+
+These work very similar to Empirical asserts, except they do not throw assertion errors. When compiled in debug mode, they will print a warning (and any desired additional information) on failure but program execution will continue. When compiled outside of debug mode they do nothing.
+
+```cpp
+#include "Empirical/include/emp/base/assert_warning.hpp"
+#include <iostream>
+
+int a = 6;
+// If compiled in debug mode, this will print a
+// warning and the value of a
+emp_assert_warning(a==5, a);
+
+// This will get printed because no assertion
+// error will be triggered
+std::cout << "Still running!" << std::endl; 
+
 ```
 
+If you want your warning to be triggered outside of debug mode, you can use {c:func}`emp_always_assert_warning`.
+
 ## Empirical pointers
 
 Ptr objects behave as normal pointers under most conditions. However, if
@@ -95,3 +115,14 @@ int_ptr.New(123456); // Store the value 123456 in int_ptr.
 std::cout << "*int_ptr = " << *int_ptr << std::endl;
 int_ptr.Delete();
 ```
+
+## API
+
+<!-- API TOC -->
+<!-- The above comment tells the API generator that this file has API docs. Don't remove it. -->
+```{eval-rst}
+.. toctree::
+   :glob:
+
+   api/*
+```

doc/library/bits/bits.md

@@ -1,36 +1,14 @@
 # Bits
 
-## BitMatrix
+Stuff about bits
 
-```{eval-rst}
-.. doxygenfile:: emp/bits/BitMatrix.hpp
-  :project: Empirical
-```
-
-## BitArray
+## API
 
+<!-- API TOC -->
+<!-- The above comment tells the API generator that this file has API docs. Don't remove it. -->
 ```{eval-rst}
-.. doxygenfile:: emp/bits/BitArray.hpp
-  :project: Empirical
-```
+.. toctree::
+   :glob:
 
-## BitSet
-
-```{eval-rst}
-.. doxygenfile:: emp/bits/BitSet.hpp
-  :project: Empirical  
+   api/*
 ```
-
-## BitSet Utilities
-
-```{eval-rst}
-.. doxygenfile:: emp/bits/bitset_utils.hpp
-  :project: Empirical
-```
-
-## BitVector
-
-```{eval-rst}
-.. doxygenfile:: emp/bits/BitVector.hpp
-  :project: Empirical
-``` 

doc/library/compiler/compiler.md

@@ -1,42 +1,12 @@
 # Compiler
 
-## Deterministic Finite Automata
+## API
 
+<!-- API TOC -->
+<!-- The above comment tells the API generator that this file has API docs. Don't remove it. -->
 ```{eval-rst}
-.. doxygenfile:: emp/compiler/DFA.hpp
-```
+.. toctree::
+   :glob:
 
-## Lexer Utilities
-
-```{eval-rst}
-.. doxygenfile:: emp/compiler/lexer_utils.hpp 
-```
-
-## Lexer
-
-```{eval-rst}
-.. doxygenfile:: emp/compiler/Lexer.hpp
-```
-
-## Non-Deterministic Finite Automata
-
-<!-- ```{eval-rst}
-.. doxygenfile:: emp/compiler/NFA.hpp
-  :sections: briefdescription detaileddescription
-.. doxygentypedef:: NFA
-.. doxygentypedef:: NFA_state
-.. doxygenclass:: emp::tNFA
-  :members:
-  :undoc-members:
-.. doxygenclass:: emp::tNFA_state
-  :members:
-  :undoc-members:  
-``` -->
-
-<!-- ## Regular Expressions
-
-```{eval-rst}
-.. doxygenfile:: emp/compiler/RegEx.hpp
-  :project: Empirical
-  :no-link:   
-``` -->
+   api/*
+```

doc/library/data/data.md

@@ -29,34 +29,11 @@ for collecting data over the course of a computational experiment.
 
 ## Data Tools API
 
-### DataNodes
-
-```{eval-rst}
-.. doxygenfile:: emp/data/DataNode.hpp
-  :project: Empirical
-  :no-link:   
-```
-
-### DataManagers
-
-```{eval-rst}
-.. doxygenfile:: emp/data/DataManager.hpp
-  :project: Empirical
-  :no-link:   
-```
-
-### DataInterfaces
-
+<!-- API TOC -->
+<!-- The above comment tells the API generator that this file has API docs. Don't remove it. -->
 ```{eval-rst}
-.. doxygenfile:: emp/data/DataInterface.hpp
-  :project: Empirical
-  :no-link:   
-```
-
-### DataFiles
+.. toctree::
+   :glob:
 
-```{eval-rst}
-.. doxygenfile:: emp/data/DataFile.hpp
-  :project: Empirical
-  :no-link:   
+   api/*
 ```