[WIP] Fix doxygen so it compiles with 0 errors and update docs

doxygen/contributor_help_pages/common_pitfalls.md

@@ -26,7 +26,7 @@ template <typename T>
 T norm(const Eigen::Matrix<T, Eigen::Dynamic, 1>&);
 ```
 
-A typical problem with a function like this is that `norm` can similarly be defined for a row vector (and the implementation is the same).
+A typical problem with a function like this is that `norm` can similarly be defined for a row vector (and the implementation is the same). 
 In this case there are two signatures:
 
 ```cpp
@@ -46,10 +46,10 @@ return_type_t<T> norm(const T&);
 But what if we want different overloads to handle different types?
 The most common situation is when there is one template overload that works with any autodiff type, and then a second faster overload that only works with a specific autodiff type.
 
-There can easily be ambiguities between the two function signatures.
-The previous examples took advantage of simple overloads.
-The more general solution is template metaprograms that additionally make use of C++ substitution failure
-is not an error (SFINAE) semantics.
+There can easily be ambiguities between the two function signatures. 
+The previous examples took advantage of simple overloads. 
+The more general solution are template metaprograms that additionally make use of C++ substitution failure
+is not an error (SFINAE) semantics. 
 For the norm function above, SFINAE could be used to limit one signature to work with reverse
 mode autodiff types and one to work with anything else:
 
@@ -65,11 +65,11 @@ template <typename T,
 return_type_t<T> norm(const T&);
 ```
 
-SFINAE should be thought of as a filter on what functions are visible to the compiler when it does a name lookup for a specific function.
-The type trait `require_st_var` should be read "require the @ref stan::scalar_type of the argument to be a @ref stan::math::var".
-The metaprogram `require_st_var<T>` will evaluate to a valid type if the scalar type of `T` is a @ref stan::math::var.
-If the scalar type of `T` is not a @ref stan::math::var, then `require_st_var<T>` does not evaluate to a valid type and the compiler treats it as if the signature does not exist.
-This is how SFINAE (substitution failure is not an error) works.
+SFINAE should be thought of as filters on what functions are visible to the compiler when it does name lookup for a specific function. 
+The type trait `require_st_var` should be read "require the @ref stan::scalar_type of the argument to be a @ref stan::math::var". 
+The metaprogram `require_st_var<T>` will evaluate to a valid type if the scalar type of `T` is a @ref stan::math::var. 
+If the scalar type of `T` is not a @ref stan::math::var, then `require_st_var<T>` does not evaluate to a valid type and the compiler treats it as if the signature does not exist. 
+This is how SFINAE (substitution failure is not an error) works. 
 Because the substitution does not work, the signature is ignored.
 This is all built based on C++'s [std::enable_if](https://en.cppreference.com/w/cpp/types/enable_if) template metaprogram.
 
@@ -143,8 +143,8 @@ auto add_zero(T&& a) {
 }
 ```
 
-Returning expressions is an advanced feature, and it is easy to make mistakes.
-In this regard, it is simplest to start development not returning expressions (in this case holders are unnecessary) and only add expression return types later.
+Returning expressions is an advanced feature and it is easy to make mistakes. 
+In this regard, it is simplest to start development not returning expressions (in this case holders are unnecessary), and only add expression return types later.
 
 It is always possible to return a non-expression type by evaluating the Eigen expression.
 For convenience, there is an `eval` function in Math that will evaluate Eigen expressions and forward anything else.
@@ -256,8 +256,8 @@ inline var cool_fun(const EigVec& v) {
 }
 ```
 
-we make a deep copy of the return whose inner `vari` will not be the same, but the `var` will produce a new copy of the pointer to the `vari`.
-Now the user code above will be protected, and it is safe for them to assign to individual elements of the `auto` returned matrix.
+we make a deep copy of the return whose inner `vari` will not be the same but the `var` will produce a new copy of the pointer to the `vari`. 
+Now the user code above will be protected and it is safe for them to assign to individual elements of the `auto` returned matrix.
 
 ### Const correctness, reverse mode autodiff, and arena types
 

doxygen/contributor_help_pages/developer_doc.md

@@ -43,7 +43,7 @@ We're committed to having a permissive open-source license. The Math library is
 
 # Contributing {#contribution}
 
-Thanks for reading! We love contributions from everyone in the form of good discussion, issues, and pull requests.
+Thanks for reading! We love contributions from everyone in the form of discussion, issues, and pull requests.
 
 ## Issues
 
@@ -87,7 +87,7 @@ Pull requests are code reviewed after they pass our continuous integration tests
 It is the responsibility of the contributor submitting the pull request that the code meets these requirements. We're open-source. Once the code gets into the code base, the community of developers take ownership of it.
 
 
-## Discussion
+## Discussion {#discussion}
 
 For general questions, please ask on the forums with the ["Developers" tag](http://discourse.mc-stan.org/c/stan-dev).
 

doxygen/contributor_help_pages/getting_started.md

@@ -150,7 +150,7 @@ for (Eigen::Index i = 0; i < x.size(); ++i) {
 }
 ```
 
-Using lazily evaluated expressions allows Eigen to avoid redundant copies, reads and writes to our data.
+Using lazily evaluated expressions allows Eigen to avoid redundant copies, reads, and writes to our data. 
 However, this comes at the cost of more complicated template traits and patterns as well as being careful around handling inputs to functions.
 
 In (3), when we access the coefficients of `x` in the loop, if its type is similar to the expression above we can get incorrect results as Eigen does not guarantee any safety of results when performing coefficient level access on an expression type that transforms its inputs.
@@ -396,8 +396,8 @@ You can think of `.val()` and `.adj()` as returning an Eigen matrix of doubles s
 
 ### (4) Setting up the reverse pass
 
-Once the forward pass is complete, and the data for the reverse pass is in the arena the adjoint calculation for the portion of the reverse pass for this function needs to be written.
-The reverse pass consists of an adjoint calculation which is placed onto the callback stack.
+Once the forward pass is complete and the data for the reverse pass is in the arena the adjoint calculation for the portion of the reverse pass for this function needs to be written. 
+The reverse pass consists of an adjoint calculation which is placed onto the callback stack. 
 When a user calls @ref stan::math::grad this adjoint calculation will be called so that adjoints are accumulated from the final output to the starting inputs.
 
 The adjoint method for a self dot product is

doxygen/docker/alpine/Dockerfile

@@ -1,8 +1,16 @@
-FROM nnadeau/docker-doxygen
+FROM alpine:3.16
+
+ARG USER_ID
+ARG GROUP_ID
+ARG DEBIAN_FRONTEND=noninteractive
 
 RUN apk update && apk add \
-  make execline
+  make execline doxygen graphviz bash g++ git
+
+#RUN addgroup -g $GROUP_ID user
+#RUN adduser --disabled-password --gecos '' --uid $USER_ID  user
 
-RUN mkdir math
-COPY . ./math
-WORKDIR ./math
+USER root
+RUN mkdir /math
+#RUN chown $USER_ID:$GROUP_ID /math
+USER user

doxygen/docker/ubuntu/Dockerfile

@@ -0,0 +1,16 @@
+FROM ubuntu:20.04
+
+ARG USER_ID
+ARG GROUP_ID
+ARG DEBIAN_FRONTEND=noninteractive
+
+RUN apk update && apk add \
+  make execline doxygen graphviz bash g++ git
+
+RUN addgroup --gid $GROUP_ID user
+RUN adduser --disabled-password --gecos '' --uid $USER_ID --gid $GROUP_ID user
+
+USER root
+RUN mkdir /math
+RUN chown $USER_ID:$GROUP_ID /math
+USER user

doxygen/doxygen.cfg

@@ -826,7 +826,7 @@ WARN_NO_PARAMDOC       = NO
 # Possible values are: NO, YES and FAIL_ON_WARNINGS.
 # The default value is: NO.
 
-WARN_AS_ERROR          = NO
+WARN_AS_ERROR          = YES
 
 # The WARN_FORMAT tag determines the format of the warning messages that doxygen
 # can produce. The string should contain the $file, $line, and $text tags, which

doxygen/pretty_stuff/standoxy.css

@@ -1,4 +1,3 @@
-
 /******** Eigen specific CSS code ************/
 
 /**** Styles removing elements ****/
@@ -152,18 +151,15 @@ h2 {
   border-width: 1px;
   border-color: #cccccc;
 }
-a#details + h2.groupheader { display:none; } 
-div.textblock { border-bottom: 1px solid #879ECB; width: 100%; }
+
 /**** Table of content in the side-nav ****/
 
 
 div.toc {
   margin:0;
   padding: 0.3em 0 0 0;
   width:100%;
-  float:none;
-  position:absolute;
-  bottom:0;
+  float: none;
   border-radius:0px;
   border-style: solid none none none;
   max-height:50%;

lib/eigen_3.3.9/Eigen/src/Core/Ref.h

@@ -10,7 +10,7 @@
 #ifndef EIGEN_REF_H
 #define EIGEN_REF_H
 
-namespace Eigen { 
+namespace Eigen {
 
 namespace internal {
 
@@ -48,7 +48,7 @@ struct traits<Ref<_PlainObjectType, _Options, _StrideType> >
     };
     typedef typename internal::conditional<MatchAtCompileTime,internal::true_type,internal::false_type>::type type;
   };
-  
+
 };
 
 template<typename Derived>
@@ -86,7 +86,7 @@ template<typename Derived> class RefBase
       m_stride(StrideType::OuterStrideAtCompileTime==Dynamic?0:StrideType::OuterStrideAtCompileTime,
                StrideType::InnerStrideAtCompileTime==Dynamic?0:StrideType::InnerStrideAtCompileTime)
   {}
-  
+
   EIGEN_INHERIT_ASSIGNMENT_OPERATORS(RefBase)
 
 protected:
@@ -110,12 +110,12 @@ template<typename Derived> class RefBase
     }
     else
       ::new (static_cast<Base*>(this)) Base(expr.data(), expr.rows(), expr.cols());
-    
+
     if(Expression::IsVectorAtCompileTime && (!PlainObjectType::IsVectorAtCompileTime) && ((Expression::Flags&RowMajorBit)!=(PlainObjectType::Flags&RowMajorBit)))
       ::new (&m_stride) StrideBase(expr.innerStride(), StrideType::InnerStrideAtCompileTime==0?0:1);
     else
       ::new (&m_stride) StrideBase(StrideType::OuterStrideAtCompileTime==0?0:expr.outerStride(),
-                                   StrideType::InnerStrideAtCompileTime==0?0:expr.innerStride());    
+                                   StrideType::InnerStrideAtCompileTime==0?0:expr.innerStride());
   }
 
   StrideBase m_stride;

makefile

@@ -89,6 +89,15 @@ doxygen:
 	doxygen -v
 	doxygen doxygen/doxygen.cfg
 	cp ./doxygen/pretty_stuff/eigen_navtree_hacks.js ./doc/api/html
+
+MAKE_DIR = $(dir $(abspath $(firstword $(MAKEFILE_LIST))))
+
+.PHONY: docker-doxygen
+docker-doxygen:
+	docker build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) -t math-doxygen ./doxygen/docker/alpine/
+	docker run -it --rm --mount "type=bind,src=$(MAKE_DIR),dst=$(MAKE_DIR)" --user "$(id -u):$(id -g)" --workdir $(MAKE_DIR) math-doxygen make doxygen
+
+
 ##
 # Clean up.
 ##

stan/math.hpp

@@ -1,6 +1,9 @@
 #ifndef STAN_MATH_HPP
 #define STAN_MATH_HPP
 
+/**
+ * Test Stan math doc
+ */
 /**
  * \defgroup prob_dists Probability Distributions
  */

stan/math/fwd/core/std_complex.hpp

@@ -29,7 +29,7 @@ class complex<stan::math::fvar<T>>
    * Construct a complex number with the specified real part and a zero
    * imaginary part.
    *
-   * @tparam Scalar real type (must be assignable to `value_type`)
+   * @tparam Scalar real type (must be assignable to \ref stan::value_type )
    * @param[in] re real part
    */
   template <typename U, typename = stan::require_stan_scalar_t<U>>