Remove "unreviewed draft" status for this document.

Add info on built-in tracker dependencies and handling of Diagram dependencies.
Update figure.
Reorganize Doxygen "Modules" grouping and get rid of accidental "aliases" module.
Recover multibody_doxygen.h from the attic.
Reduce repetitive hyperlinking.

attic/multibody/collision/collision_filter_doxygen.h

@@ -1,4 +1,4 @@
-/** @defgroup collision_concepts Collision Concepts
+/** @addtogroup collision_concepts
 
 In the real world, we can rely on the axiom that no two objects can occupy the
 same space at the same time; the universe provides this constraint for free. In

bindings/pydrake/pydrake_pybind.h

@@ -164,6 +164,19 @@ in `pybind`, and ensure that the trampoline class inherits from the
 `py::wrapper<>` class specific to our fork of `pybind`. This ensures that no
 slicing happens with the subclassed instances.
 
+## Convenience aliases
+
+Some aliases are provided; prefer these to the full spellings.
+
+`namespace py` is a shorthand alias to `pybind11` for consistency.
+
+@see py_reference, py_reference_internal for dealing with %common ownership
+     issues.
+
+@note Downstream users should avoid `using namespace drake::pydrake`, as
+this may create ambiguous aliases (especially for GCC). Instead, consider
+an alias.
+
 # Interactive Debugging with Bazel
 
 If you would like to interactively debug binding code (using IPython for
@@ -204,13 +217,9 @@ If using CLion, consider using `gdbserver`.
 
 // TODO(eric.cousineau): Add API naming conventions (#7819).
 
-/// @defgroup Convenience aliases
-/// @{
-
-/// Shorthand alias to `pybind` for consistency.
-/// @note Downstream users should avoid `using namespace drake::pydrake`, as
-/// this may create ambiguous aliases (especially for GCC). Instead, consider
-/// an alias.
+// Note: Doxygen apparently doesn't process comments for namespace aliases. If
+// you put Doxygen comments here they will apply instead to py_reference. See
+// the "Convenience aliases" section above for documentation.
 namespace py = pybind11;
 
 /// Used when returning `T& or `const T&`, as pybind's default behavior is to
@@ -223,8 +232,6 @@ const auto py_reference = py::return_value_policy::reference;
 const auto py_reference_internal =
     py::return_value_policy::reference_internal;
 
-/// @}
-
 // Implementation for `overload_cast_explicit`. We must use this structure so
 // that we can constrain what is inferred. Otherwise, the ambiguity confuses
 // the compiler.

common/doxygen_cxx.h

@@ -1,3 +1,2 @@
 /// @defgroup cxx C++ support features
-/// @{
-/// @}
+/// @ingroup drake_technical_notes

doc/doxygen.h

@@ -53,12 +53,23 @@ out the Doxygen C++ documentation</a></p>
 only updated nightly.</p>
 
 <h3>Technical Notes</h3>
-These links provide notes on Drake's design and implementation.
+These links provide notes on Drake's theory, design, and implementation.
 
 - @ref multibody_concepts
+- @ref collision_concepts
 - @ref cache_design_notes
+- @ref system_scalar_conversion
 
 */
+// Define groups here so we can contol the ordering.
+// TODO(sherm1) Change Collision Concepts title here when #9467 is fixed.
+/**
+  @defgroup systems Modeling Dynamical Systems
+  @defgroup solvers Formulating and Solving Optimization Problems
+  @defgroup multibody_concepts Multibody Dynamics Concepts
+  @defgroup collision_concepts Collision Concepts (RigidBodyPlant only)
+  @defgroup drake_technical_notes Technical Notes
+*/
 
 
 

multibody/constraint/constraint_doxygen.h

@@ -1,4 +1,5 @@
 /** @defgroup constraint_overview Multibody dynamics constraints in Drake
+    @ingroup multibody_concepts
 
 This documentation describes the types of multibody constraints supported in
 Drake, including specialized constraint types- namely point-based contact

multibody/multibody_doxygen.h

@@ -6,7 +6,7 @@
 // To link to the Spatial Inertia discussion: @ref multibody_spatial_inertia.
 
 //------------------------------------------------------------------------------
-/** @defgroup multibody_concepts Multibody Dynamics Concepts
+/** @addtogroup multibody_concepts
 
 Translating from the mathematics of multibody mechanics to correct code is a
 difficult process and requires careful discipline to ensure that the resulting

solvers/mathematical_program.h

@@ -38,7 +38,7 @@
 namespace drake {
 namespace solvers {
 
-/** @defgroup solvers Formulating and Solving Optimization Problems
+/** @addtogroup solvers
  * @{
  * Drake wraps a number of commercial solvers (+ a few custom solvers) to
  * provide a common interface for convex optimization, mixed-integer convex

systems/framework/context.h

@@ -197,7 +197,7 @@ class Context : public ContextBase {
     return get_parameters().get_abstract_parameter(index);
   }
   //@}
-
+  /** @anchor context_value_change_methods */
   /// @name           Methods for changing locally-stored values
   /// Methods in this group allow changes to the values of quantities stored
   /// locally in this %Context. The changeable quantities are:

systems/framework/context_base.h

@@ -277,6 +277,7 @@ class ContextBase : public internal::ContextMessageInterface {
   }
   //@}
 
+  /// @anchor context_base_change_notification_methods
   /** @name         Change notification methods (Internal use only)
   These "Note" methods are used by framework-internal derived classes to effect
   change notifications that propagate down from a DiagramContext (where the

systems/framework/leaf_system.h

@@ -1033,6 +1033,8 @@ class LeafSystem : public System<T> {
 
   // =========================================================================
   /// @name                    Declare output ports
+  /// @anchor DeclareLeafOutputPort_documentation
+  ///
   /// Methods in this section are used by derived classes to declare their
   /// output ports, which may be vector valued or abstract valued. Every output
   /// port must have an _allocator_ function and

systems/framework/system_scalar_conversion_doxygen.h

@@ -1,5 +1,6 @@
 //------------------------------------------------------------------------------
 /** @defgroup system_scalar_conversion System Scalar Conversion
+    @ingroup drake_technical_notes
 
 System scalar conversion refers to cloning a System templatized by one scalar
 type into an identical System that is templatized by a different scalar type.

systems/systems.h

@@ -1,5 +1,5 @@
 
-/// @defgroup systems Modeling Dynamical Systems
+/// @addtogroup systems
 /// @{
 /// @brief Drake uses a Simulink-inspired description of dynamical systems.
 ///