[SymForce-External] Epsilon tutorial, rename ops tutorial

Import of #135 ORIGINAL_AUTHOR = Aaron Miller [email protected] - Epsilon tutorial, rename ops tutorial - More docs and tutorials updates - add intro to epsilon tutorial - Update optimization tutorial - Update README.md - Update wording on build in readme - Rename requirements.txt to dev_requirements.txt - Update theme settings - skymarshal updates - update sym packaging - Fix more stuff - Fix dev.rst, new badges + classifiers - Fix skymarshal setup.py - Data files, sym -> symforce-sym, scipy required - Fix tests, hopefully - Bump version to 0.4.0 - Fix tests
symforce-org · May 24, 2022 · ad2a796 · ad2a796
1 parent 0bb830d
commit ad2a796
Show file tree

Hide file tree

Showing 22 changed files with 650 additions and 447 deletions.
diff --git a/README.md b/README.md
@@ -8,8 +8,10 @@
 <a href="https://symforce.org"><img alt="Documentation" src="https://img.shields.io/badge/api-docs-blue" /></a>
 <a href="https://github.com/symforce-org/symforce"><img alt="Source Code" src="https://img.shields.io/badge/source-code-blue" /></a>
 <a href="https://github.com/symforce-org/symforce/issues"><img alt="Issues" src="https://img.shields.io/badge/issue-tracker-blue" /></a>
-<img alt="Python 3.8" src="https://img.shields.io/badge/python-3.8-blue" />
+<img alt="Python 3.8 | 3.9 | 3.10" src="https://img.shields.io/pypi/pyversions/symforce" />
 <img alt="C++14" src="https://img.shields.io/badge/c++-14-blue" />
+<a href="https://pypi.org/project/symforce/"><img alt="PyPI" src="https://img.shields.io/pypi/v/symforce" /></a>
+<a href="https://github.com/symforce-org/symforce/tree/main/LICENSE"><img alt="Apache License" src="https://img.shields.io/pypi/l/symforce" /></a>
 </p>
 
 ---
@@ -48,88 +50,30 @@ SymForce is developed and maintained by [Skydio](https://skydio.com/). It is use
 SymForce was published to [RSS 2022](https://roboticsconference.org/). Please cite it as follows:
 
 ```
-@inproceedings{Martiros-RSS-22, 
-    author    = {Hayk Martiros AND Aaron Miller AND Nathan Bucki AND Bradley Solliday AND Ryan Kennedy AND Jack Zhu AND Tung Dang AND Dominic Pattison AND Harrison Zheng AND Teo Tomic AND Peter Henry AND Gareth Cross AND Josiah VanderMey AND Alvin Sun AND Samuel Wang AND Kristen Holtz}, 
-    title     = {{SymForce: Symbolic Computation and Code Generation for Robotics}}, 
-    booktitle = {Proceedings of Robotics: Science and Systems}, 
-    year      = {2022}, 
-    doi       = {10.15607/RSS.2022.XVIII.041} 
-} 
+@inproceedings{Martiros-RSS-22,
+    author    = {Hayk Martiros AND Aaron Miller AND Nathan Bucki AND Bradley Solliday AND Ryan Kennedy AND Jack Zhu AND Tung Dang AND Dominic Pattison AND Harrison Zheng AND Teo Tomic AND Peter Henry AND Gareth Cross AND Josiah VanderMey AND Alvin Sun AND Samuel Wang AND Kristen Holtz},
+    title     = {{SymForce: Symbolic Computation and Code Generation for Robotics}},
+    booktitle = {Proceedings of Robotics: Science and Systems},
+    year      = {2022},
+    doi       = {10.15607/RSS.2022.XVIII.041}
+}
 ```
 
-# Build from pip
+# Install
 
-SymForce requires Python 3.8 or later. We suggest creating a virtual python environment.
+Install with pip:
 
-Install the `gmp` package with one of:
-```
-apt install libgmp-dev            # Linux
-brew install gmp                  # Mac
-conda install -c conda-forge gmp  # Conda
-```
-
-Install SymForce
-```
-pip install -e .
+```bash
+pip install symforce
 ```
 
 Verify the installation in Python:
 ```python
 >>> from symforce import geo
 >>> geo.Rot3()
 ```
-<span style="color:blue">TODO: Create wheels for <code style="color:blue"><b>pip install symforce</b></code></span>
-
-# Build CMake yourself (TODO deconflict)
-
-SymForce requires Python 3.8 or later. We suggest creating a virtual python environment.
-
-Install packages:
-```
-# Linux
-apt install doxygen libgmp-dev pandoc
-
-# Mac
-brew install doxygen gmp pandoc
-
-# Conda
-conda install -c conda-forge doxygen gmp pandoc
-```
-
-Install python requirements:
-```
-pip install -r requirements.txt
-```
 
-Install CMake if you don't already have a recent version:
-```
-pip install "cmake>=3.19"
-```
-
-Build SymForce (requires C++14 or later):
-```
-mkdir build
-cd build
-cmake ..
-make -j 7
-```
-If you have build errors, try updating CMake.
-
-Install built Python packages:
-```
-cd ..
-pip install -e build/lcmtypes/python2.7
-pip install -e gen/python
-pip install -e .
-```
-
-Verify the installation in Python:
-```python
->>> from symforce import geo
->>> geo.Rot3()
-```
-
-<span style="color:blue">TODO: Create wheels for <code style="color:blue"><b>pip install symforce</b></code></span>
+This installs pre-compiled C++ components of SymForce on Linux and Mac using pip wheels, but does not include C++ headers. If you want to compile against C++ SymForce types (like `sym::Optimizer`), you currently need to [build from source](#build-from-source).
 
 # Tutorial
 
@@ -226,7 +170,7 @@ geo.V3.symbolic("x").norm(epsilon=sm.epsilon)
 
 <!-- $\sqrt{x_0^2 + x_1^2 + x_2^2 + \epsilon}$ -->
 
-<span style="color:blue">TODO: Link to a detailed epsilon tutorial once created.</span>
+See the [Epsilon Tutorial](https://symforce.org/notebooks/epsilon_tutorial.html) in the SymForce Docs for more information.
 
 ## Build an optimization problem
 
@@ -574,6 +518,52 @@ $ -->
 
 To learn more, visit the SymForce tutorials [here](https://symforce.org/#guides).
 
+# Build from Source
+
+SymForce requires Python 3.8 or later. We strongly suggest creating a virtual python environment.
+
+Install the `gmp` package with one of:
+```bash
+apt install libgmp-dev            # Ubuntu
+brew install gmp                  # Mac
+conda install -c conda-forge gmp  # Conda
+```
+
+SymForce contains both C++ and Python code. The C++ code is built using CMake.  You can build the package either by calling pip, or by calling CMake directly.  If building with `pip`, this will call CMake under the hood, and run the same CMake build for the C++ components.
+
+If you encounter build issues, please file an [issue](https://github.com/symforce-org/symforce/issues).
+
+## Build with pip
+
+The recommended way to build and install SymForce if you only plan on making Python changes is with pip.  From the symforce directory:
+```bash
+pip install -e .
+```
+
+This will build the C++ components of SymForce, but you won't be able to run `pip install -e .` repeatedly if you need to rebuild C++ code.  If you're changing C++ code and rebuilding, you should build with CMake directly as described [below](#build-with-cmake).
+
+`pip install .` will not install pinned versions of SymForce's dependencies, it'll install any compatible versions.  It also won't install all packages required to run all of the SymForce tests and build all of the targets (e.g. building the docs or running the linters).  If you want all packages required for that, you should `pip install .[dev]` instead (or one of the other groups of extra requirements in our `setup.py`).  If you additionally want pinned versions of our dependencies, which are the exact versions guaranteed by CI to pass all of our tests, you can install them from `pip install -r dev_requirements.txt`.
+
+## Build with CMake
+
+If you'll be modifying the C++ parts of SymForce, you should build with CMake directly instead - this method will not install
+SymForce into your Python environment, so you'll need to add it to your PYTHONPATH separately.
+
+Install python requirements:
+```bash
+pip install -r dev_requirements.txt
+```
+
+Build SymForce (requires C++14 or later):
+```bash
+mkdir build
+cd build
+cmake ..
+make -j $(nproc)
+```
+
+You'll then need to add SymForce (along with `gen/python` and `third_party/skymarshal` within symforce) to your PYTHONPATH in order to use them.
+
 # License
 
 SymForce is released under the [Apache 2.0](https://spdx.org/licenses/Apache-2.0.html) license.

diff --git a/requirements.txt → dev_requirements.txt b/requirements.txt → dev_requirements.txt
@@ -65,7 +65,6 @@ docutils==0.17.1
     #   myst-parser
     #   nbsphinx
     #   sphinx
-    #   sphinx-rtd-theme
 entrypoints==0.4
     # via
     #   jupyter-client
@@ -177,15 +176,19 @@ nest-asyncio==1.5.5
 numpy==1.22.3
     # via
     #   matplotlib
+    #   pandas
     #   scipy
     #   skymarshal
     #   symforce (setup.py)
+    #   symforce-sym
 packaging==21.3
     # via
     #   ipykernel
     #   matplotlib
     #   nbconvert
     #   sphinx
+pandas==1.4.2
+    # via symforce (setup.py)
 pandocfilters==1.5.0
     # via nbconvert
 parso==0.8.3
@@ -206,6 +209,8 @@ platformdirs==2.5.1
     # via
     #   black
     #   pylint
+plotly==5.8.0
+    # via symforce (setup.py)
 ply==3.11
     # via skymarshal
 prompt-toolkit==3.0.29
@@ -235,8 +240,11 @@ python-dateutil==2.8.2
     # via
     #   jupyter-client
     #   matplotlib
+    #   pandas
 pytz==2022.1
-    # via babel
+    # via
+    #   babel
+    #   pandas
 pyyaml==6.0
     # via myst-parser
 pyzmq==22.3.0
@@ -263,12 +271,9 @@ sphinx==4.5.0
     #   myst-parser
     #   nbsphinx
     #   sphinx-autodoc-typehints
-    #   sphinx-rtd-theme
     #   symforce (setup.py)
 sphinx-autodoc-typehints==1.14.1
     # via symforce (setup.py)
-sphinx-rtd-theme==1.0.0
-    # via symforce (setup.py)
 sphinxcontrib-applehelp==1.0.2
     # via sphinx
 sphinxcontrib-devhelp==1.0.2
@@ -287,6 +292,8 @@ file:./gen/python
     # via symforce (setup.py)
 sympy==1.10.1
     # via symforce (setup.py)
+tenacity==8.0.1
+    # via plotly
 tinycss2==1.1.1
     # via nbconvert
 tokenize-rt==4.2.1

diff --git a/docs/conf.py b/docs/conf.py
@@ -114,27 +114,34 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "alabaster"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 html_theme_options = {
+    "description": "Fast symbolic computation, code generation, and nonlinear optimization for robotics",
+    "fixed_sidebar": False,
+    "page_width": "1200px",
+    "github_button": True,
+    "github_user": "symforce-org",
+    "github_repo": "symforce",
+    "github_type": "star",
     # 'canonical_url': '',
     # 'analytics_id': 'UA-XXXXXXX-1',  #  Provided by Google in your dashboard
     # 'logo_only': False,
-    "display_version": True,
+    # "display_version": True,
     # 'prev_next_buttons_location': 'bottom',
     # 'style_external_links': False,
     # 'vcs_pageview_mode': '',
     # 'style_nav_header_background': 'white',
     # Toc options
-    "collapse_navigation": False,
-    "sticky_navigation": True,
-    "navigation_depth": -1,
-    "includehidden": True,
-    "titles_only": True,
+    # "collapse_navigation": False,
+    # "sticky_navigation": True,
+    # "navigation_depth": -1,
+    "sidebar_includehidden": True,
+    # "titles_only": True,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

diff --git a/docs/development.rst b/docs/development.rst
@@ -15,12 +15,19 @@ See the :ref:`module reference <api-reference>` for the core package structure.
 *************************************************
 Build
 *************************************************
-SymForce is primarily written in Python, aimed to be 3.8+ compatible. It has a top level Makefile to execute high level commands:
+SymForce is primarily written in Python and C++, and is Python 3.8+ and C++14 compatible.  The build
+system is CMake for the C++ components, and optionally pip / setuptools on top for Python packaging.
+See the Build section on the [Homepage](/index.html#build-from-source) for build instructions.
+
+
+*************************************************
+Additional useful commands
+*************************************************
+SymForce also has a top level Makefile which is not used by the build, but provides some high
+level commands for development:
 
 +----------------------------------------------+--------------------------+
-| Install requirements                         | ``make all_reqs``        |
-+----------------------------------------------+--------------------------+
-| Run tests                                    | ``make test``            |
+| Run Python tests                             | ``make test``            |
 +----------------------------------------------+--------------------------+
 | Run tests which update (most) generated code | ``make test_update``     |
 +----------------------------------------------+--------------------------+
@@ -32,18 +39,12 @@ SymForce is primarily written in Python, aimed to be 3.8+ compatible. It has a t
 +----------------------------------------------+--------------------------+
 | Build docs + open in browser                 | ``make docs_open``       |
 +----------------------------------------------+--------------------------+
-| Launch Jupyter server                        | ``make notebook``        |
-+----------------------------------------------+--------------------------+
-| Launch Jupyter server + browser              | ``make notebook_open``   |
-+----------------------------------------------+--------------------------+
 | Run the code formatter (black, clang-format) | ``make format``          |
 +----------------------------------------------+--------------------------+
 | Check types with mypy                        | ``make check_types``     |
 +----------------------------------------------+--------------------------+
 | Check formatting and types                   | ``make lint``            |
 +----------------------------------------------+--------------------------+
-| Clean all build products                     | ``make clean``           |
-+----------------------------------------------+--------------------------+
 
 *************************************************
 Documentation

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,25 +1,31 @@
-SymForce Docs
+SymForce Home
 =============
 
 .. include:: ../README.md
    :parser: myst_parser.sphinx_
 
-Guides
-======
-
 .. toctree::
    :caption: Pages
    :hidden:
 
    self
    development
+
+.. toctree::
+   :caption: Tutorials
+   :hidden:
+
    notebooks/sympy_tutorial
    notebooks/geometry_tutorial
    notebooks/ops_tutorial
    notebooks/cameras_tutorial
    notebooks/values_tutorial
    notebooks/codegen_tutorial
    notebooks/optimization_tutorial
+   notebooks/epsilon_tutorial
+
+Guides
+======
 
 :doc:`development`
     How to build, configure, and develop
@@ -31,7 +37,7 @@ Guides
     Introductory guide to doing math and geometry
 
 :doc:`notebooks/ops_tutorial`
-    Introductory guide to using Concepts in symforce
+    Introductory guide to using Ops in symforce
 
 :doc:`notebooks/cameras_tutorial`
     Introductory guide to using camera models
@@ -45,6 +51,9 @@ Guides
 :doc:`notebooks/optimization_tutorial`
     Basic example of using generated code to do optimization
 
+:doc:`notebooks/epsilon_tutorial`
+    Guide to how Epsilon is used to prevent singularities
+
 .. _api-reference:
 .. toctree::
     :hidden:

diff --git a/docs/notebooks/epsilon_tutorial.ipynb b/docs/notebooks/epsilon_tutorial.ipynb
@@ -0,0 +1 @@
+../../notebooks/epsilon_tutorial.ipynb