Merge pull request #94 from robotology/docs

Move from Doxygen documentation to m.css
robotology · May 4, 2021 · b45c337 · b45c337
2 parents ed46d2b + 97d955c
commit b45c337
Show file tree

Hide file tree

Showing 7 changed files with 2,844 additions and 72 deletions.
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -1,50 +1,55 @@
-name: GitHub Pages
-
+name: gh-pages
 on:
   push:
-    branches:
-    - 'master'
+    branches: master
 
 jobs:
-  docs:
-    name: "Deploy"
+  build:
     runs-on: ubuntu-20.04
-
     steps:
       - uses: actions/checkout@master
-      - uses: webfactory/[email protected]
-        with:
-          ssh-private-key: ${{ secrets.SSH_PRIVATE_GH_PAGES }}
+
       - name: Dependencies
         run: |
           sudo apt update
-          sudo apt install -y doxygen graphviz
+          sudo apt install -y xsltproc texlive ghostscript graphviz texlive-base texlive-latex-extra texlive-fonts-extra texlive-fonts-recommended flex bison
+          git clone --depth 1 --branch Release_1_9_1 https://github.com/doxygen/doxygen.git
+          cd doxygen && mkdir build && cd build
+          cmake -G "Unix Makefiles" ..
+          sudo make install
 
-      - name: Check remote
-        run: git ls-remote --heads --exit-code https://github.com/${{ github.repository }}.git gh-pages
+      - name: Fetch Python deps
+        run: python3 -m pip install jinja2 Pygments docutils
 
-      - name: Configure Git
-        run: |
-          git config --global push.default upstream
-          git config --global user.name "GitHub Actions"
-          git config --global user.email "[email protected]"
-
-      - name: Clone and rebase
+      - name: Fetch m.css
         run: |
           cd ${GITHUB_WORKSPACE}
-          git clone [email protected]:${{ github.repository }}.git gh-pages
-          cd gh-pages
-          git checkout gh-pages
-          git rebase master
+          git clone git://github.com/mosra/m.css
 
-      - name: Build Doxygen
+      - name: Build docs
         run: |
-          cd ${GITHUB_WORKSPACE}/gh-pages/doxygen
-          doxygen ./generate.txt
+          cd docs
+          mkdir site
+          python3 ${GITHUB_WORKSPACE}/m.css/documentation/doxygen.py conf.py
 
-      - name: Commit and push
-        run: |
-          cd ${GITHUB_WORKSPACE}/gh-pages
-          git add .
-          git commit --amend --no-edit
-          git push --force-with-lease
+      - name: Archive artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: site
+          path: docs/site
+
+  deploy:
+    runs-on: ubuntu-20.04
+    needs: [build]
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v2
+        with:
+          name: site
+          path: site
+      - name: Deploy
+        uses: JamesIves/[email protected]
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: site
diff --git a/README.md b/README.md
@@ -1,49 +1,54 @@
-<p align="center">
-<h1 align="center">osqp-eigen</h1>
-</p>
+# osqp-eigen
 
-<p align="center">
-<a href="https://isocpp.org"><img src="https://img.shields.io/badge/standard-C++14-blue.svg?style=flat&logo=c%2B%2B" alt="C++ Standard"/></a>
-<a href="./LICENSE"><img src="https://img.shields.io/badge/license-LGPL-19c2d8.svg" alt="Size" /></a>
-<a href="https://www.codacy.com/manual/GiulioRomualdi/osqp-eigen?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=robotology/osqp-eigen&amp;utm_campaign=Badge_Grade"><img src="https://api.codacy.com/project/badge/Grade/a73c260e38d949eabeecc424410d859c"/></a>
-<a href="https://github.com/robotology/osqp-eigen/workflows/C++%20CI%20Workflow/badge.svg"><img src="https://github.com/robotology/osqp-eigen/workflows/C++%20CI%20Workflow/badge.svg"/></a>
-</p>
+| [![c++14](https://img.shields.io/badge/standard-C++14-blue.svg?style=flat&logo=c%2B%2B)](https://isocpp.org) | [![License](https://img.shields.io/badge/license-LGPL-19c2d8.svg)](https://github.com/robotology/osqp-eigen/blob/master/LICENSE) | [![Code quality](https://api.codacy.com/project/badge/Grade/a73c260e38d949eabeecc424410d859c)](https://www.codacy.com/manual/GiulioRomualdi/osqp-eigen?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=robotology/osqp-eigen&amp;utm_campaign=Badge_Grade) | [![CI](https://github.com/robotology/osqp-eigen/workflows/C++%20CI%20Workflow/badge.svg)](https://github.com/robotology/osqp-eigen/workflows/C++%20CI%20Workflow/badge.svg) |
+| :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: |
+| | | | |
 
 Simple C++ wrapper for [osqp](http://osqp.readthedocs.io/en/latest/index.html) library.
 
+## Documentation
+The documentation is available online at the accompanying [website](https://robotology.github.io/osqp-eigen).
 
-## Dependeces
-- [osqp](http://osqp.readthedocs.io/en/latest/index.html) of course :smile:;
-- [Eigen3](http://eigen.tuxfamily.org/index.php?title=Main_Page);
-- [cmake](https://cmake.org/);
-- [Catch2](https://github.com/catchorg/Catch2) (only for testing).
-
-## Build the library and the application
-### Linux / macOs
-```sh
-git clone https://github.com/robotology/osqp-eigen.git
-cd osqp-eigen
-mkdir build && cd build
-cmake ../
-make
-[sudo] make install
-```
-If you want to enable tests set the `BUILD_TESTING` option to `ON`.
 
-**Notice**: ``sudo`` is not necessary if you specify the ``CMAKE_INSTALL_PREFIX``. In this case it is necessary to add in the ``.bashrc`` the following lines:
-
-### Linux / macOs
-```
-export OsqpEigen_DIR=/path/where/you/installed/
+## Dependeces
+The project depends only on [`osqp`](http://osqp.readthedocs.io/en/latest/index.html) and [Eigen3](http://eigen.tuxfamily.org/index.php?title=Main_Page). Please install [Catch2](https://github.com/catchorg/Catch2)  if you want to run the tests only for testing.
+
+## Usage
+1. Clone the repository
+
+   ```
+   git clone https://github.com/robotology/osqp-eigen.git
+   ```
+2. Build it
+
+   ```
+   cd osqp-eigen
+   mkdir build
+   cd build
+   cmake -DCMAKE_INSTALL_PREFIX:PATH=<custom-folder> ../
+   make
+   make install
+   ```
+3. Add the following environmental variable
+   ```
+   OsqpEigen_DIR=/path/where/you/installed/
+   ```
+
+## How to use the library
+**osqp-eigen** provides native `CMake` support which allows the library to be easily used in `CMake` projects.
+**osqp-eigen** exports a CMake target called `OsqpEigen::OsqpEigen` which can be imported using the `find_package` CMake command and used by calling `target_link_libraries` as in the following example:
+```cmake
+cmake_minimum_required(VERSION 3.0)
+project(myproject)
+find_package(OsqpEigen REQUIRED)
+add_executable(example example.cpp)
+target_link_libraries(example OsqpEigen::OsqpEigen)
 ```
 
-**Notice**:  The choice of `OsqpEigen_DIR` name for the environment variable is not random. Indeed `<package>_DIR` is one of the search paths of [`find_package()`](https://cmake.org/cmake/help/v3.0/command/find_package.html).
-
-## How to use the wrapper
-[Here](./example/) you can find a simple example that shows how to use this library.
+## Bug reports and support
+All types of [issues](https://github.com/robotology/osqp-eigen/issues/new) are welcome.
 
-## API
-[Here](https://robotology.github.io/osqp-eigen/) you can find the documentation.
+## License
+Materials in this repository are distributed under the following license:
 
-## Bug reports and support
-All types of [issues](https://github.com/robotology/osqp-eigen/issues/new) are welcome :smile:.
+> All software is licensed under the LGPL3 License. See [LICENSE](https://github.com/robotology/osqp-eigen/blob/master/LICENSE) file for details.