Add tutorial (#31)

ipc-sim · Mar 18, 2023 · dff890f · dff890f
1 parent 7ce485e
commit dff890f
Show file tree

Hide file tree

Showing 17 changed files with 906 additions and 101 deletions.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,6 +1,8 @@
 sphinx
 sphinx-sitemap
 sphinx-immaterial
+autoclasstoc
+# sphinx-autodoc-toolbox
 breathe
 nbsphinx
 pandoc

diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
@@ -2,6 +2,50 @@ span.colon {
     margin-left: -1em;
 }
 
+dl.cpp.objdesc, dl.py.objdesc {
+    /* border: 0.05rem solid var(--md-primary-fg-color); */
+    border: 0.05rem solid rgb(68, 138, 255);
+    box-shadow: var(--md-shadow-z1);
+    border-radius: 0.4rem;
+    overflow: hidden;
+}
+
+dl.cpp.objdesc > dt, dl.py.objdesc > dt {
+    padding-left: 0.5rem;
+    padding-right: 0.5rem;
+}
+
+dl.cpp.objdesc > dd, dl.py.objdesc > dd {
+    margin: 0 1.875em;
+}
+
+dl.py.objdesc > dd > details.toggle-details {
+    border: 0.05rem solid var(--md-primary-fg-color);
+    box-shadow: var(--md-shadow-z1);
+    border-radius: 0.4rem;
+    overflow: hidden;
+}
+
+dl.py.objdesc > dd > details.toggle-details > summary {
+    border: 0;
+    font-size: 0.8rem;
+}
+
+dl.py.objdesc > dd > details.toggle-details > summary::before,
+dl.py.objdesc > dd > details.toggle-details > summary::after {
+    background-color: var(--md-primary-fg-color--light);
+    /* background-color: currentcolor; */
+    top: auto;
+}
+
+dl.py.objdesc > dd > details.toggle-details > summary > svg.tb-icon {
+    display: none;
+}
+
+table.autosummary {
+    font-size: 0.75rem !important;
+}
+
 /* .breatheparameterlist li tt + p {
     display: inline;
   }

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -37,7 +37,9 @@
 # extensions coming with Sphinx (named "sphinx.ext.*") or your custom
 # ones.
 extensions = [
+    "autoclasstoc",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosectionlabel",
@@ -51,7 +53,13 @@
     "myst_parser",
     "nbsphinx",
     "sphinx_immaterial",
-    "sphinx_immaterial.apidoc.python.apigen"
+    "sphinx_immaterial.apidoc.python.apigen",
+    "sphinx_immaterial.apidoc.format_signatures",
+    # 'sphinx_autodoc_toolbox.collapse',
+]
+
+object_description_options = [
+    ("cpp:.*", dict(clang_format_style={"BasedOnStyle": "WebKit"})),
 ]
 
 source_suffix = {
@@ -69,10 +77,23 @@
     project: "../build/doxyoutput/xml"
 }
 breathe_default_project = project
-breathe_default_members = ("members", "undoc-members")
+breathe_default_members = (
+    "members",
+    "undoc-members",
+    "protected-members",
+    "private-members",
+)
 breathe_show_define_initializer = True
 # breathe_show_include = True
 
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "private-members": True,
+    'special-members': True,
+    'show-inheritance': True,
+}
+
 # -- GraphViz configuration ----------------------------------
 graphviz_output_format = 'svg'
 
@@ -163,7 +184,8 @@
         "navigation.tracking",
         "search.highlight",
         "search.share",
-        "toc.follow"
+        "toc.follow",
+        "content.tabs.link"
     ],
 
     "font": {

diff --git a/docs/source/cpp-api/broad_phase.rst b/docs/source/cpp-api/broad_phase.rst
@@ -5,16 +5,34 @@ Broad Phase
 
 .. doxygenvariable:: ipc::DEFAULT_BROAD_PHASE_METHOD
 
+Broad Phase
+-----------
+
 .. doxygenclass:: ipc::BroadPhase
 
-.. doxygenclass:: ipc::AABB
+Brute Force
+-----------
 
 .. doxygenclass:: ipc::BruteForce
 
+Hash Grid
+---------
+
 .. doxygenclass:: ipc::HashGrid
 
+Spatial Hash
+------------
+
 .. doxygenclass:: ipc::SpatialHash
 
+Sweep and Tiniest Queue
+-----------------------
+
 .. doxygenclass:: ipc::SweepAndTiniestQueue
 
 .. .. doxygenclass:: ipc::SweepAndTiniestQueueGPU
+
+AABB
+----
+
+.. doxygenclass:: ipc::AABB
diff --git a/docs/source/cpp-api/candidates.rst b/docs/source/cpp-api/candidates.rst
@@ -1,13 +1,47 @@
 Candidates
 ==========
 
+Candidates
+----------
+
 .. doxygenclass:: ipc::Candidates
 
+Collision Stencil
+-----------------
+
 .. doxygenclass:: ipc::CollisionStencil
+
+
+Continuous Collision Candidate
+------------------------------
+
 .. doxygenclass:: ipc::ContinuousCollisionCandidate
 
+
+Vertex-Vertex Candidate
+-----------------------
+
 .. doxygenclass:: ipc::VertexVertexCandidate
+
+
+Edge-Vertex Candidate
+---------------------
+
 .. doxygenclass:: ipc::EdgeVertexCandidate
+
+
+Edge-Edge Candidate
+-------------------
+
 .. doxygenclass:: ipc::EdgeEdgeCandidate
+
+
+Edge-Face Candidate
+-------------------
+
 .. doxygenclass:: ipc::EdgeFaceCandidate
+
+Face-Vertex Candidate
+---------------------
+
 .. doxygenclass:: ipc::FaceVertexCandidate
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -7,6 +7,15 @@ changelog
 license
 ```
 
+```{toctree}
+:caption: Tutorial
+:hidden:
+
+tutorial/getting_started.rst
+tutorial/simulation.rst
+tutorial/misc.rst
+```
+
 ```{toctree}
 :caption: C++
 :hidden:
@@ -48,5 +57,7 @@ style_guide
 Code of Conduct <code_of_conduct.md>
 ```
 
+<!-- <img src="_static/teaser@0_3.png" style="padding: 15px 30px 0; background-color: white; width: calc(100% - 60px); max-width: 600px; margin: auto; display: block;"/> -->
+
 ```{include} ../../README.md
 ```
diff --git a/docs/source/python-api/broad_phase.rst b/docs/source/python-api/broad_phase.rst
@@ -2,27 +2,52 @@ Broad Phase
 ===========
 
 .. autoclass:: ipctk.BroadPhaseMethod
-    :members:
+
+    .. autoclasstoc::
 
 .. .. autovariable:: ipctk.DEFAULT_BROAD_PHASE_METHOD
 
+Broad Phase
+-----------
+
 .. autoclass:: ipctk.BroadPhase
-    :members:
 
-.. autoclass:: ipctk.AABB
-    :members:
+    .. autoclasstoc::
+
+Brute Force
+-----------
 
 .. autoclass:: ipctk.BruteForce
-    :members:
+
+    .. autoclasstoc::
+
+Hash Grid
+---------
 
 .. autoclass:: ipctk.HashGrid
-    :members:
+
+    .. autoclasstoc::
+
+Spatial Hash
+------------
 
 .. autoclass:: ipctk.SpatialHash
-    :members:
+
+    .. autoclasstoc::
+
+Sweep and Tiniest Queue
+-----------------------
 
 .. autoclass:: ipctk.SweepAndTiniestQueue
-    :members:
+
+    .. autoclasstoc::
 
 .. .. autoclass:: ipctk.SweepAndTiniestQueueGPU
-..     :members:
+..     :members:
+
+AABB
+----
+
+.. autoclass:: ipctk.AABB
+
+    .. autoclasstoc::
diff --git a/docs/source/python-api/candidates.rst b/docs/source/python-api/candidates.rst
@@ -1,26 +1,59 @@
 Candidates
 ==========
 
+Candidates
+----------
+
 .. autoclass:: ipctk.Candidates
-    :members:
+
+    .. autoclasstoc::
+
+Collision Stencil
+-----------------
+
+.. error::
+    This ``autoclass`` is not working. I don't know why. I have to investigate.
 
 .. .. autoclass:: ipctk.CollisionStencil
-..     :members:
+
+Continuous Collision Candidate
+------------------------------
+
 .. autoclass:: ipctk.ContinuousCollisionCandidate
-    :members:
+
+    .. autoclasstoc::
+
+Vertex-Vertex Candidate
+-----------------------
 
 .. autoclass:: ipctk.VertexVertexCandidate
-    :members:
-    :show-inheritance:
+
+    .. autoclasstoc::
+
+Edge-Vertex Candidate
+---------------------
+
 .. autoclass:: ipctk.EdgeVertexCandidate
-    :members:
-    :show-inheritance:
+
+    .. autoclasstoc::
+
+Edge-Edge Candidate
+-------------------
+
 .. autoclass:: ipctk.EdgeEdgeCandidate
-    :members:
-    :show-inheritance:
+
+    .. autoclasstoc::
+
+Edge-Face Candidate
+-------------------
+
 .. autoclass:: ipctk.EdgeFaceCandidate
-    :members:
-    :show-inheritance:
+
+    .. autoclasstoc::
+
+Face-Vertex Candidate
+---------------------
+
 .. autoclass:: ipctk.FaceVertexCandidate
-    :members:
-    :show-inheritance:
+
+    .. autoclasstoc::