Documentation improvements (#840)

* docs: rsync with --delete to remove outdated pages on docs page

* docs: update start page

* docs: edit on Github link using html_context

* docs: use sphinx-build

* docs: nicer badges with links

* docs: fix link

* docs: add Contents overview to home page

* docs: work on acados problem formulation; link HPIPM guide

docs/Makefile

@@ -36,7 +36,8 @@
 # Based on the sphinx-quickstart Makefile template.
 
 SPHINXOPTS    =
-SPHINXBUILD   = python -msphinx
+# SPHINXBUILD   = python -msphinx
+SPHINXBUILD   = sphinx-build
 DOXYBUILD     = doxygen
 SPHINXPROJ    = acados
 SOURCEDIR     = .
@@ -63,7 +64,7 @@ doxygen:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 upload:
-	rsync -aP -e ssh $(BUILDDIR)/* acados_website@syscop.de:~/website_public/
+	rsync -aP -e ssh $(BUILDDIR)/ acados_website@syscop.de:~/website_public/ --delete
 
 clean:
 	@echo Clean Sphinx

docs/conf.py

@@ -45,7 +45,6 @@
 #
 import os
 import sys
-import subprocess
 import datetime
 
 import recommonmark
@@ -69,6 +68,17 @@
 now = datetime.datetime.now()
 copyright = str(now.year) +', syscop'
 author = 'syscop'
+github_url = "https://github.com/acados/acados"
+
+# https://stackoverflow.com/questions/62904172/how-do-i-replace-view-page-source-with-edit-on-github-links-in-sphinx-rtd-th
+# These variables are intended to be set directly in the .rst files rather than in html_theme_options or conf.py in general. To make this actually apply site-wide as if it were defined in every .rst file, just put it in html_context.
+# TODO: use rst files everywhere to get rid of this.
+html_context = {
+  'display_github': True,
+  'github_user': 'acados',
+  'github_repo': 'acados',
+  'github_version': 'master/docs/',
+}
 
 
 # -- General configuration ---------------------------------------------------

docs/index.md

@@ -1,22 +1,47 @@
 # acados
 
 <!-- ![](https://secure.travis-ci.org/acados/acados.png?branch=master) -->
-![Github actions full build workflow](https://github.com/acados/acados/actions/workflows/full_build.yml/badge.svg)
+
+```eval_rst
+
+|github-workflow-full-build|
+
+|github-workflow-c_test_blasfeo_reference|
+
+.. |github-workflow-full-build| image:: https://github.com/acados/acados/actions/workflows/full_build.yml/badge.svg
+    :target: https://github.com/acados/acados/actions/workflows/full_build.yml
+    :alt: Github workflow status
+
+.. |github-workflow-c_test_blasfeo_reference| image:: https://github.com/acados/acados/actions/workflows/c_test_blasfeo_reference.yml/badge.svg
+    :target: https://github.com/acados/acados/actions/workflows/c_test_blasfeo_reference.yml
+    :alt: Github workflow status
+
+```
+
+
 <!-- ![Github actions full build workflow](https://github.com/acados/acados/actions/workflows/full_build.yml/badge.svg?branch=master) -->
 ![](https://ci.appveyor.com/api/projects/status/q0b2nohk476u5clg?svg=true)
 
 Fast and embedded solvers for nonlinear optimal control.
 
+- `acados` __source code__ is hosted on [Github](https://github.com/acados/acados).
+Contributions via Pull requests are welcome!
+
+- `acados` has a discourse based [__forum__](https://discourse.acados.org/).
+
+- `acados` is mainly developed by the group around Prof. Moritz Diehl, the Systems Control and Optimization Laboratory (__syscop__), at the University of Freiburg. [More infos on the syscop web page](https://www.syscop.de/).
+
+
+
 ```eval_rst
 Documentation latest build: |today|
 ```
 
 
 ```eval_rst
 .. toctree::
-   :hidden:
    :maxdepth: 2
-   :caption: User Documentation
+   :caption: Contents
 
    about_acados/index
    problem_formulation/index

docs/problem_formulation/index.md

@@ -1,4 +1,19 @@
 # Problem Formulation
 
+Since `acados` mainly aims on providing SQP type methods for optimal control, it naturally needs optimal control structured nonlinear programming formulations (OCP NLP) and quadratic programming (QP) formulations to tackle the subproblems within SQP.
+
+## Optimal control structured NLP (OCP NLP)
+
 The problem formulation targeted by `acados` OCP solver is stated here:
 [https://github.com/acados/acados/blob/master/docs/problem_formulation/problem_formulation_ocp_mex.pdf](https://github.com/acados/acados/blob/master/docs/problem_formulation/problem_formulation_ocp_mex.pdf)
+
+
+## QP formulations (dense and OCP structured)
+
+`acados` relies on `HPIPM` for reformulating QP problems via (partial) condensing and expansion routines.
+In order to use them efficiently, we use the flexible QP formulations from `HPIPM`.
+Those are the optimal control structured quadratic programming formulation (OCP QP) and the
+dense QP formulation.
+
+Both problem formulations are documented in the [`HPIPM guide`](https://github.com/giaf/hpipm/blob/master/doc/guide.pdf).
+

docs/python_interface/index.md

@@ -71,7 +71,7 @@ The following image shows an overview of the available classes in the `acados` P
     :align: center
 ```
 
-## acados OCP solver interface
+## 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.
 
 The interface to interact with the acados OCP solver in C is based on [ctypes](https://cython.org/).
@@ -108,7 +108,8 @@ The cython based wrapper is called [`AcadosOcpSolverCython`](#acados_template.ac
 
 
 
-## acados integrator interface
+## acados integrator interface -- `AcadosSim` and `AcadosSimSolver`
+
 The class `AcadosSim` can be used to formulate a simulation problem, for which an acados integrator (`AcadosSimSolver`) can be created.
 The interface to interact with the acados integrator in C is based on ctypes.