[WIP] adds contributor guides to the docs #2350

SteveBronder · 2021-02-03T19:57:58Z

Summary

This takes @bbbales2 #192 PR and adds it to the stan math docs. I broke things up a bit into separate sections and fleshed out an example based on Ben's stuff. I like the example because it's pretty much real Stan math code and I think makes it easier to see the context on how we use the special widgets etc. we have. I'd like to add another example that's a bit more complicated for something like multiply but I'll do that later. This still needs some heavy editing and I'll tag people for particular sections.

This also changes the settings in doxygen.cfg so that even if there are warnings the docs are still built. I think it's annoying that some versions of doxygen compile the docs fine while others don't. This is most entirely because of warnings like

stan/math/rev/functor/idas_integrator.hpp:63: warning: argument 'dae' from the argument list of stan::math::idas_integrator::solve has multiple @param documentation sections

Which comes from us having a lot of different specializations and doxygen having trouble working out the docs for each. So I set the WARN_AS_ERROR flag for doxygen to NO

# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
# a warning is encountered.
# The default value is: NO.

WARN_AS_ERROR          = NO

Release notes

Adds docs for new contributors

Checklist

Math issue #(issue number)
Copyright holder: Steve Bronder

The copyright holder is typically you or your assignee, such as a university or company. By submitting this pull request, the copyright holder is agreeing to the license the submitted work under the following licenses:
- Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
- Documentation: CC-BY 4.0 (https://creativecommons.org/licenses/by/4.0/)
the basic tests are passing
- unit tests pass (to run, use: ./runTests.py test/unit)
- header checks pass, (make test-headers)
- dependencies checks pass, (make test-math-dependencies)
- docs build, (make doxygen)
- code passes the built in C++ standards checks (make cpplint)
the code is written in idiomatic C++ and changes are documented in the doxygen
the new changes are tested

SteveBronder · 2021-02-03T19:58:38Z

You can make the docs locally by running make doxygen

bbbales2 · 2021-02-03T20:52:47Z

Nice nice! Yeah gimme bite size pieces and happy to add on.

SteveBronder · 2021-02-03T23:36:46Z

doxygen/contributor_help_pages/common_pitfalls.md

+}
+```
+
+### Holders


Tagging @t4c1 and @andrjohns can you both look this over to make sure it covers the problem and solution well?

Looks fine to me.

SteveBronder · 2021-02-03T23:38:36Z

doxygen/contributor_help_pages/common_pitfalls.md

+2. If you are writing a function for reverse mode, pass values by `const&`
+3. In prim, if you are confident and working with larger types, use perfect forwarding to pass values that can be moved from. Otherwise simply pass values by `const&`.
+
+### Copying non-arena variables to lambdas used in the reverse pass


@bbbales2 can you add make_callback_ptr() stuff here?

SteveBronder · 2021-02-03T23:39:10Z

doxygen/contributor_help_pages/common_pitfalls.md

+### Nested Stacks
+
+### Scoped Stacks
+
+As an aside, in order to get the actual vector result, Eigen defines the
+`.eval()` operator, so `c.eval()` would return an actual `Eigen::VectorXd`.
+Similarly, Math defines the `eval` function which will evaluate an Eigen
+expression and forward anything that is not an Eigen expression.


@wds15 would you have time to write about Stan's threading scheme for the allocators? I think that would be best to put here

SteveBronder · 2021-02-03T23:40:43Z

doxygen/contributor_help_pages/getting_started.md

+TL;DR: Use Stan's `require` type trait library for limiting a function's scope to certain types.
+
+Reading from left to right, `require_not_st_var_t` requires that a signature's template does _not_ have a _scalar type_ that is Stan's `var` autodiff type. This line is exactly the same as


[todo: me] add link to requires docs

SteveBronder · 2021-02-03T23:41:45Z

doxygen/contributor_help_pages/getting_started.md

+an autodiff type from the argument `x`. The function `f` is called on the
+reverse pass similarly to `reverse_pass_callback`.
+
+## Argument Types


Maybe everything here should go in another page?

SteveBronder · 2021-02-03T23:42:20Z

doxygen/contributor_help_pages/getting_started.md

+## Reverse Mode
+
+### Values
+
+`value_of(x)` returns the values of the variable `x`. If `x` is not an
+autodiff type, it simply forwards `x` along. The values of `x` have
+the same shape as `x`. For reverse mode autodiff, values are `double`
+variables. For higher order autodiff (`fvar<var>`, etc.) this is not
+always the case. See `value_of_rec` for a different behavior.
+
+### Values and adjoint extensions to Eigen
+


This should probs go somewhere else as well

SteveBronder · 2021-02-03T23:43:36Z

I'm going to try to restructure this a lil bit tmrw. I'd like to better structure this like Eigen's docs

rok-cesnovar · 2021-02-05T18:59:09Z

Question: Do we want to add which checks to run locally before submitting a PR? Also a note on clang-format and the rest?
If yes I can handle that.

SteveBronder · 2021-02-05T21:50:08Z

Yeah that would be awesome! I think that would go under the testing section

SteveBronder · 2021-03-26T15:45:00Z

@rok-cesnovar if you have time to write up the PR stuff that would be rad but otherwise I think this is good to go!

rok-cesnovar · 2021-03-26T16:02:07Z

Will do over the weekend.

rok-cesnovar · 2021-04-07T11:42:32Z

Obviously that weekend has long passed. Lets merge this.

adds constructor guide to the docs

99eaa8f

SteveBronder commented Feb 3, 2021

View reviewed changes

bbbales2 added 2 commits February 5, 2021 12:22

Added section on make_callback_ptr

e6ac525

Added Tadej's comments from other thread

faa61b7

bbbales2 mentioned this pull request Feb 5, 2021

[WIP] Feature/math guide stan-dev/example-models#192

Closed

SteveBronder added 2 commits March 26, 2021 11:11

Merge remote-tracking branch 'origin/develop' into docs/intro-guide

e681791

update docs

8a5115d

rok-cesnovar approved these changes Apr 7, 2021

View reviewed changes

SteveBronder merged commit b542337 into develop Apr 7, 2021

SteveBronder deleted the docs/intro-guide branch April 7, 2021 14:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] adds contributor guides to the docs #2350

[WIP] adds contributor guides to the docs #2350

SteveBronder commented Feb 3, 2021

SteveBronder commented Feb 3, 2021

bbbales2 commented Feb 3, 2021

SteveBronder Feb 3, 2021

t4c1 Feb 4, 2021

SteveBronder Feb 3, 2021

bbbales2 Feb 5, 2021

SteveBronder Feb 3, 2021

SteveBronder Feb 3, 2021

SteveBronder Feb 3, 2021

SteveBronder Feb 3, 2021

SteveBronder commented Feb 3, 2021

rok-cesnovar commented Feb 5, 2021

SteveBronder commented Feb 5, 2021

SteveBronder commented Mar 26, 2021

rok-cesnovar commented Mar 26, 2021

rok-cesnovar commented Apr 7, 2021

		TL;DR: Use Stan's `require` type trait library for limiting a function's scope to certain types.

		Reading from left to right, `require_not_st_var_t` requires that a signature's template does _not_ have a _scalar type_ that is Stan's `var` autodiff type. This line is exactly the same as

[WIP] adds contributor guides to the docs #2350

[WIP] adds contributor guides to the docs #2350

Conversation

SteveBronder commented Feb 3, 2021

Summary

Release notes

Checklist

SteveBronder commented Feb 3, 2021

bbbales2 commented Feb 3, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SteveBronder commented Feb 3, 2021

rok-cesnovar commented Feb 5, 2021

SteveBronder commented Feb 5, 2021

SteveBronder commented Mar 26, 2021

rok-cesnovar commented Mar 26, 2021

rok-cesnovar commented Apr 7, 2021