Skip to content

Commit

Permalink
Bugfixes for documentation build (issues #305, 307)
Browse files Browse the repository at this point in the history
- 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)
  • Loading branch information
katta committed Apr 22, 2020
1 parent 25e654c commit c24348f
Show file tree
Hide file tree
Showing 10 changed files with 26 additions and 43 deletions.
10 changes: 9 additions & 1 deletion .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ addons:
- python3-pip
- doxygen
- pandoc
- texlive-base
- dvipng
# for Mac builds, we use Homebrew
homebrew:
packages:
Expand Down Expand Up @@ -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

#=============================================================================
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
```
Expand Down
33 changes: 1 addition & 32 deletions docs/DoxygenLayout.xml
Original file line number Diff line number Diff line change
@@ -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"/>
Expand All @@ -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=""/>
Expand Down Expand Up @@ -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=""/>
Expand All @@ -117,8 +99,6 @@
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
Expand All @@ -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=""/>
Expand All @@ -154,8 +129,6 @@
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
Expand All @@ -176,8 +149,6 @@
<classes visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
Expand All @@ -196,8 +167,6 @@
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
Expand Down
6 changes: 6 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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",
Expand All @@ -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"],
Expand Down
2 changes: 1 addition & 1 deletion src/codegen/codegen_c_visitor.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down
4 changes: 2 additions & 2 deletions src/language/templates/ast/ast.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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);
};
Expand Down
2 changes: 1 addition & 1 deletion src/language/templates/visitors/checkparent_visitor.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion src/visitors/sympy_solver_visitor.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion src/visitors/sympy_solver_visitor.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down

0 comments on commit c24348f

Please sign in to comment.