Bugfixes for documentation build (issues #305, 307)

- m2r & sphinx>=3.0 are not compatible (more info in pr in progress
  in m2r: miyakogi/m2r#55)
- add path in conf.py to find the nmodl module
- removed various doxygen warnings due to unacceptable keywords
  in configuration files
- adjust checkparent_visitor sphinx autodoc /copybrief
- reduce the maxium number of processors used to build documentation
  (it was freezing my workstation)

Author: katta

.travis.yml

@@ -43,6 +43,8 @@ addons:
       - python3-pip
       - doxygen
       - pandoc
+      - texlive-base
+      - dvipng
   # for Mac builds, we use Homebrew
   homebrew:
     packages:
@@ -77,7 +79,13 @@ install:
   - pip3 install -U pip setuptools
   - pip3 install Jinja2 PyYAML pytest sympy --user
   - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then
-      pip3 install -U --user sphinx nbsphinx>=0.3.2 m2r sphinx-rtd-theme jupyter;
+      # there is a bug in m2r if sphinx>2.4.4. There is a pr in m2r to solve the
+      # issue here: https://github.com/miyakogi/m2r/pull/55 . When it is done
+      # I will remove the sphinx downgrade. Change setup.py requirements when it
+      # be the case
+      #
+      # Katta
+      pip3 install -U --user sphinx==2.4.4 nbsphinx>=0.3.2 m2r sphinx-rtd-theme jupyter;
     fi
 
 #=============================================================================

CONTRIBUTING.md

@@ -107,7 +107,7 @@ repository:
 If you are developing NMODL, make sure to enable both `NMODL_FORMATTING` and `NMODL_PRECOMMIT`
 CMake variables to ensure that your contributions follow the coding conventions of this project:
 
-```cmake
+```
 cmake -DNMODL_FORMATTING:BOOL=ON -DNMODL_PRECOMMIT:BOOL=ON <path>
 ```
 

docs/DoxygenLayout.xml

@@ -1,5 +1,6 @@
 <doxygenlayout version="1.0">
   <!-- Generated by doxygen 1.8.15 -->
+  <!-- adapted to doxygen 1.8.13 (Katta) -->
   <!-- Navigation index tabs for HTML output -->
   <navindex>
     <tab type="mainpage" visible="yes" title="Overview"/>
@@ -9,26 +10,12 @@
       <tab type="namespacelist" visible="yes" title="" intro=""/>
       <tab type="namespacemembers" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="interfaces" visible="yes" title="">
-      <tab type="interfacelist" visible="yes" title="" intro=""/>
-      <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
-      <tab type="interfacehierarchy" visible="yes" title="" intro=""/>
-    </tab>
     <tab type="classes" visible="yes" title="">
       <tab type="classlist" visible="yes" title="" intro=""/>
       <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="hierarchy" visible="yes" title="" intro=""/>
       <tab type="classmembers" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="structs" visible="yes" title="">
-      <tab type="structlist" visible="yes" title="" intro=""/>
-      <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
-    </tab>
-    <tab type="exceptions" visible="yes" title="">
-      <tab type="exceptionlist" visible="yes" title="" intro=""/>
-      <tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
-      <tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
-    </tab>
     <tab type="files" visible="yes" title="">
       <tab type="filelist" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
@@ -102,13 +89,8 @@
     <memberdecl>
       <nestednamespaces visible="yes" title=""/>
       <constantgroups visible="yes" title=""/>
-      <interfaces visible="yes" title=""/>
       <classes visible="yes" title=""/>
-      <structs visible="yes" title=""/>
-      <exceptions visible="yes" title=""/>
       <typedefs title=""/>
-      <sequences title=""/>
-      <dictionaries title=""/>
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
@@ -117,8 +99,6 @@
     <memberdef>
       <inlineclasses title=""/>
       <typedefs title=""/>
-      <sequences title=""/>
-      <dictionaries title=""/>
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
@@ -135,16 +115,11 @@
     <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
     <sourcelink visible="yes"/>
     <memberdecl>
-      <interfaces visible="yes" title=""/>
       <classes visible="yes" title=""/>
-      <structs visible="yes" title=""/>
-      <exceptions visible="yes" title=""/>
       <namespaces visible="yes" title=""/>
       <constantgroups visible="yes" title=""/>
       <defines title=""/>
       <typedefs title=""/>
-      <sequences title=""/>
-      <dictionaries title=""/>
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
@@ -154,8 +129,6 @@
       <inlineclasses title=""/>
       <defines title=""/>
       <typedefs title=""/>
-      <sequences title=""/>
-      <dictionaries title=""/>
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
@@ -176,8 +149,6 @@
       <classes visible="yes" title=""/>
       <defines title=""/>
       <typedefs title=""/>
-      <sequences title=""/>
-      <dictionaries title=""/>
       <enums title=""/>
       <enumvalues title=""/>
       <functions title=""/>
@@ -196,8 +167,6 @@
       <inlineclasses title=""/>
       <defines title=""/>
       <typedefs title=""/>
-      <sequences title=""/>
-      <dictionaries title=""/>
       <enums title=""/>
       <enumvalues title=""/>
       <functions title=""/>

docs/conf.py

@@ -17,11 +17,17 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+
+
+
 import os
 import subprocess
 import sys
 import textwrap
 
+# The project needs to be built before documentation in the usual build folder
+sys.path.insert(0, os.path.abspath('../build/lib/python'))
+
 import nmodl  # isort:skip
 
 # Run doxygen

setup.py

@@ -100,7 +100,7 @@ def build_extension(self, ext):
             build_args += ["--", "/m"]
         else:
             cmake_args += ["-DCMAKE_BUILD_TYPE=" + cfg]
-            build_args += ["--", "-j{}".format(max(1, os.cpu_count() - 1))]
+            build_args += ["--", "-j{}".format(max(1, os.cpu_count() - 3))]
 
         env = os.environ.copy()
         env["CXXFLAGS"] = '{} -DVERSION_INFO=\\"{}\\"'.format(
@@ -147,7 +147,7 @@ def run(self):
         )
 
 
-install_requirements = ["jinja2>=2.9", "PyYAML>=3.13", "sympy>=1.3"]
+install_requirements = ["jinja2>=2.9.3", "PyYAML>=3.13", "sympy>=1.3"]
 
 setup(
     name="NMODL",
@@ -167,7 +167,7 @@ def run(self):
         buildhtml=get_sphinx_command,
     ),
     zip_safe=False,
-    setup_requires=["nbsphinx>=0.3.2", "m2r", "sphinx-rtd-theme", "sphinx>=2.0"]
+    setup_requires=["nbsphinx>=0.3.2", "m2r", "sphinx-rtd-theme", "sphinx>=2.0", "sphinx<3.0"]
     + install_requirements,
     install_requires=install_requirements,
     tests_require=["pytest>=3.7.2"],

src/codegen/codegen_c_visitor.hpp

@@ -1785,7 +1785,7 @@ class CodegenCVisitor: public visitor::AstVisitor {
      * Find unique variable name defined in nmodl::utils::SingletonRandomString by the
      * nmodl::visitor::SympySolverVisitor
      * @param original_name Original name of variable to change
-     * @return std::string Unique name produced as <original_name>_<random_string>
+     * @return std::string Unique name produced as "original_string"_"random_string"
      */
     std::string find_var_unique_name(const std::string& original_name);
 

src/language/templates/ast/ast.hpp

@@ -333,7 +333,7 @@ struct Ast: public std::enable_shared_from_this<Ast> {
    * returning a raw pointer may create less problems that the
    * shared_from_this from the parent.
    *
-   * \ref Check Ast::parent for more information
+   * Check \ref Ast::parent for more information
    */
   virtual Ast* get_parent() const;
 
@@ -345,7 +345,7 @@ struct Ast: public std::enable_shared_from_this<Ast> {
    * we set children parents directly in the parent constructor using
    * set_parent_in_children()
    *
-   * \ref Check Ast::parent for more information
+   *  Check \ref Ast::parent for more information
    */
   virtual void set_parent(Ast* p);
 };

src/language/templates/visitors/checkparent_visitor.hpp

@@ -17,7 +17,7 @@
  * \brief Auto generated visitors
  *
  * \file
- * \brief \copybrief nmodl::visitor::CheckParentVisitor
+ * \brief \copybrief nmodl::visitor::test::CheckParentVisitor
  */
 
 #include "visitors/ast_visitor.hpp"

src/visitors/sympy_solver_visitor.cpp

@@ -159,7 +159,7 @@ std::string SympySolverVisitor::suffix_random_string(const std::string& original
     auto singleton_random_string_class = nmodl::utils::SingletonRandomString<4>::instance();
     // Check if there is a variable defined in the mod file as original_string and if yes
     // try to use a different string for the matrices created by sympy in the form
-    // <original_string>_<random_string>
+    // "original_string"_"random_string"
     while (vars.find(new_string) != vars.end()) {
         random_string = singleton_random_string_class->reset_random_string(original_string);
         new_string = original_string;

src/visitors/sympy_solver_visitor.hpp

@@ -109,7 +109,7 @@ class SympySolverVisitor: public AstVisitor {
                                                   const std::string& original_string,
                                                   const std::string& substitution_string) const;
 
-    /// Return a std::string in the form <original_string>_<random_string>, where
+    /// Return a std::string in the form "original_string"_"random_string", where
     /// random_string is a string defined in the nmodl::utils::SingletonRandomString
     /// for the original_string
     std::string suffix_random_string(const std::string& original_string) const;