From 91c718de371ba8272cbee15668e2ffaba6f2733c Mon Sep 17 00:00:00 2001 From: sandmaennchen Date: Mon, 16 Sep 2024 12:02:06 +0200 Subject: [PATCH 1/3] more sub headlines in python API docs --- docs/conf.py | 1 + docs/index.md | 2 +- docs/python_interface/index.md | 48 +++++++++++++++++++++++++--------- 3 files changed, 38 insertions(+), 13 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 7c594c3a4c..f919b8ede6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -117,6 +117,7 @@ "use_source_button": True, "use_issues_button": True, "show_navbar_depth": 1, # 2 looks nice, but only extends for real subpages, like C interface, which is not so relevant + "show_toc_level": 1, } # Add any paths that contain custom static files (such as style sheets) here, diff --git a/docs/index.md b/docs/index.md index 2c6935e7bc..51207f27d5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -85,6 +85,6 @@ Documentation latest build: |today| interfaces/index python_interface/index matlab_octave_interface/index - c_interface/index + embedded_workflow/index ``` diff --git a/docs/python_interface/index.md b/docs/python_interface/index.md index 32f334c3c9..0924bcb7b6 100644 --- a/docs/python_interface/index.md +++ b/docs/python_interface/index.md @@ -103,16 +103,19 @@ The following image shows an overview of the available classes in the `acados` P :align: center ``` -## acados OCP solver interface -- `AcadosOcp` and `AcadosOcpSolver` -The class [`AcadosOcp`](#acados_template.acados_ocp.AcadosOcp) can be used to formulate optimal control problems (OCP), for which an acados solver ([`AcadosOcpSolver`](#acados_template.acados_ocp_solver.AcadosOcpSolver)) can be created. +## `acados` OCP solver interface -The interface to interact with the acados OCP solver in C is based on [ctypes](https://cython.org/). +The class [`AcadosOcp`](#acados_template.acados_ocp.AcadosOcp) can be used to formulate optimal control problems (OCP), for which an `acados` solver ([`AcadosOcpSolver`](#acados_template.acados_ocp_solver.AcadosOcpSolver)) can be created. + +The interface to interact with the `acados` OCP solver in C is based on [ctypes](https://cython.org/). Additionally, there is the option to use a Cython based wrapper around the C part. This offers faster interaction with the solver, because getter and setter calls, which include shape checking are done in compiled C code. The cython based wrapper is called [`AcadosOcpSolverCython`](#acados_template.acados_ocp_solver.AcadosOcpSolverCython) and was added in [PR #791](https://github.com/acados/acados/pull/791). `AcadosOcpSolverCython` and `AcadosOcpSolver` offer the same functionality and equivalent behavior is ensured in CI tests. + +### `AcadosOcpSolver` ``` eval_rst .. automodule:: acados_template.acados_ocp_solver :members: @@ -120,8 +123,7 @@ The cython based wrapper is called [`AcadosOcpSolverCython`](#acados_template.ac :exclude-members: make_ocp_dims_consistent ``` - - +### `AcadosOcp` ``` eval_rst .. automodule:: acados_template.acados_ocp :members: @@ -129,6 +131,7 @@ The cython based wrapper is called [`AcadosOcpSolverCython`](#acados_template.ac :exclude-members: ``` +### `AcadosOcpCost` ``` eval_rst .. automodule:: acados_template.acados_ocp_cost :members: @@ -136,6 +139,7 @@ The cython based wrapper is called [`AcadosOcpSolverCython`](#acados_template.ac :exclude-members: ``` +### `AcadosOcpConstraints` ``` eval_rst .. automodule:: acados_template.acados_ocp_constraints :members: @@ -143,6 +147,7 @@ The cython based wrapper is called [`AcadosOcpSolverCython`](#acados_template.ac :exclude-members: ``` +### `AcadosOcpOptions` ``` eval_rst .. automodule:: acados_template.acados_ocp_options :members: @@ -150,16 +155,16 @@ The cython based wrapper is called [`AcadosOcpSolverCython`](#acados_template.ac :exclude-members: ``` +### `AcadosOcpDims` ``` eval_rst .. automodule:: acados_template.acados_dims - :members: + :members: AcadosOcpDims :private-members: :exclude-members: ``` - - +### `AcadosModel` ``` eval_rst .. automodule:: acados_template.acados_model :members: @@ -169,11 +174,13 @@ The cython based wrapper is called [`AcadosOcpSolverCython`](#acados_template.ac -## acados integrator interface -- `AcadosSim` and `AcadosSimSolver` +## `acados` integrator interface -The class `AcadosSim` can be used to formulate a simulation problem, for which an acados integrator (`AcadosSimSolver`) can be created. +The class [`AcadosSim`](#acados_template.acados_sim.AcadosSim) can be used to formulate a simulation problem, for which an acados integrator, [`AcadosSimSolver`](#acados_template.acados_sim_solver.AcadosSimSolver), can be created. The interface to interact with the acados integrator in C is based on ctypes. + +### `AcadosSim` ``` eval_rst .. automodule:: acados_template.acados_sim :members: @@ -181,7 +188,7 @@ The interface to interact with the acados integrator in C is based on ctypes. :exclude-members: ``` - +### `AcadosSimSolver` ``` eval_rst .. automodule:: acados_template.acados_sim_solver :members: @@ -189,6 +196,23 @@ The interface to interact with the acados integrator in C is based on ctypes. :exclude-members: make_ocp_dims_consistent ``` +### `AcadosSimOptions` +``` eval_rst +.. automodule:: acados_template.acados_sim + :members: AcadosSimOptions + :private-members: + :exclude-members: make_ocp_dims_consistent +``` + +### `AcadosSimDims` +``` eval_rst +.. automodule:: acados_template.acados_dims + :members: AcadosSimDims + :private-members: + :exclude-members: make_ocp_dims_consistent +``` + + ## Builders The default builder for `acados` is `make` using a `Makefile` generated by `acados`. If cross-platform compatibility is required `CMake` can be used to build the binaries required by the solvers. @@ -199,7 +223,7 @@ If cross-platform compatibility is required `CMake` can be used to build the bin ``` -## acados multi-phase OCP +## `acados` multi-phase OCP Advanced feature interface to formulate multi-phase OCPs. Added in From aedbe36e042d845b08e8108dd34968d124b3f08b Mon Sep 17 00:00:00 2001 From: Jonathan Frey Date: Mon, 16 Sep 2024 13:26:05 +0200 Subject: [PATCH 2/3] exclude C interface from docs --- docs/Makefile | 5 +++-- docs/index.md | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 9622bf1496..46d950f239 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -40,7 +40,7 @@ SPHINXPROJ = acados SOURCEDIR = . BUILDDIR = _build GENERATED = .doctrees _static _sources .buildinfo .nojekyll genindex.html objects.inv search.html searchindex.js -DOXYBUILDDIR = _build_doxygen_c_interface _build_doxygen +DOXYBUILDDIR = _build_doxygen # _build_doxygen_c_interface default: doxygen html @@ -52,9 +52,10 @@ html: @$(SPHINXBUILD) -b $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) doxygen: - @$(DOXYBUILD) c_interface/Doxyfile @$(DOXYBUILD) doxygen/Doxyfile +# @$(DOXYBUILD) c_interface/Doxyfile + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/docs/index.md b/docs/index.md index 51207f27d5..5a45793cba 100644 --- a/docs/index.md +++ b/docs/index.md @@ -85,6 +85,7 @@ Documentation latest build: |today| interfaces/index python_interface/index matlab_octave_interface/index - embedded_workflow/index ``` + + \ No newline at end of file From 25f50da852b94d0216ed49a6b50366fbdac21854 Mon Sep 17 00:00:00 2001 From: Jonathan Frey Date: Mon, 16 Sep 2024 13:26:38 +0200 Subject: [PATCH 3/3] remove duplicate members --- docs/python_interface/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/python_interface/index.md b/docs/python_interface/index.md index 0924bcb7b6..a9d1f0b515 100644 --- a/docs/python_interface/index.md +++ b/docs/python_interface/index.md @@ -167,7 +167,7 @@ The cython based wrapper is called [`AcadosOcpSolverCython`](#acados_template.ac ### `AcadosModel` ``` eval_rst .. automodule:: acados_template.acados_model - :members: + :members: AcadosModel :private-members: :exclude-members: ``` @@ -183,7 +183,7 @@ The interface to interact with the acados integrator in C is based on ctypes. ### `AcadosSim` ``` eval_rst .. automodule:: acados_template.acados_sim - :members: + :members: AcadosSim :private-members: :exclude-members: ```