Merge pull request #8 from Pressio/6-brainstorm-best-way-to-document-…

…what-this-library-offers

#6: Add documentation

.github/workflows/deploy-docs.yml

@@ -0,0 +1,40 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  build-and-deploy-docs:
+    runs-on: ubuntu-latest
+    env:
+      docs-directory: /home/runner/work/pressio/pressio-ops/docs
+      python-version: '3.10'
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ env.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.python-version }}
+          architecture: 'x64'
+      - name: Install Python dependencies
+        run: |
+          pip3 install -r ./docs/build_requirements.txt
+      - name: Build documentation
+        working-directory: ${{ env.docs-directory }}
+        run: |
+          make html
+      # .nojekyll file is needed for GitHub Pages to know it's getting a ready webpage
+      # and there is no need to generate anything
+      - name: Generate nojekyll file
+        working-directory: ${{ env.docs-directory }}/generated_docs
+        run: touch .nojekyll
+      # This action moves the content of `generated_docs` to the branch from where
+      # the site is published
+      - name: Deploy docs
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: website-deployment
+          folder: ${{ env.docs-directory }}/generated_docs
+          clean: true

.gitignore

@@ -0,0 +1,2 @@
+.vscode
+generated_docs

LICENSE

@@ -5,37 +5,37 @@
 // Copyright 2019 National Technology & Engineering Solutions of Sandia,LLC
 //                              (NTESS)
 //
-// Under the terms of Contract DE-NA0003525 with NTESS, the 
+// Under the terms of Contract DE-NA0003525 with NTESS, the
 // U.S. Government retains certain rights in this software.
 //
 // Pressio is licensed under BSD-3-Clause terms of use:
 //
 // Redistribution and use in source and binary forms, with or without
-// modification, are permitted provided that the following conditions 
+// modification, are permitted provided that the following conditions
 // are met:
 //
-// 1. Redistributions of source code must retain the above copyright 
+// 1. Redistributions of source code must retain the above copyright
 // notice, this list of conditions and the following disclaimer.
-// 
-// 2. Redistributions in binary form must reproduce the above copyright 
-// notice, this list of conditions and the following disclaimer in the 
+//
+// 2. Redistributions in binary form must reproduce the above copyright
+// notice, this list of conditions and the following disclaimer in the
 // documentation and/or other materials provided with the distribution.
-// 
-// 3. Neither the name of the copyright holder nor the names of its 
-// contributors may be used to endorse or promote products derived 
+//
+// 3. Neither the name of the copyright holder nor the names of its
+// contributors may be used to endorse or promote products derived
 // from this software without specific prior written permission.
 //
-// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
-// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
-// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
-// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
-// COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
-// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
-// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
-// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
-// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 
-// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
-// IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+// COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+// IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 // POSSIBILITY OF SUCH DAMAGE.
 //
 // Questions? Contact Francesco Rizzi ([email protected])

docs/Makefile

@@ -0,0 +1,5 @@
+html:
+	sphinx-build -b html ./source/ ./generated_docs/
+
+clean:
+	rm -rf ./generated_docs/

docs/build_requirements.txt

@@ -0,0 +1,7 @@
+Sphinx==5.0.1
+furo==2022.6.4.1
+myst-parser==0.18.0
+sphinx-copybutton==0.5.0
+m2r2==0.3.2
+sphinx-design
+attrs