Add Docs test action (#1)

* Add Docs test action Signed-off-by: jparisu <[email protected]> * Fix some stuff Signed-off-by: jparisu <[email protected]> * Fix spelling Signed-off-by: jparisu <[email protected]> * Fix some docs stuff Signed-off-by: jparisu <[email protected]> * Final touches Signed-off-by: jparisu <[email protected]> --------- Signed-off-by: jparisu <[email protected]>
jparisu · Feb 1, 2024 · 28ec0d5 · 28ec0d5
1 parent 153ab38
commit 28ec0d5
Show file tree

Hide file tree

Showing 14 changed files with 112 additions and 42 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,34 @@
+name: Build and Test Documentation
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.x'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r docs/requirements.txt
+
+    - name: Build documentation
+      run: |
+        sphinx-build -b html docs/ docs/_build/html
+
+    - name: Documentation tests
+      run: |
+        sphinx-build -W --keep-going -b spelling docs/ docs/_build/spelling
diff --git a/docs/conf.py b/docs/conf.py
@@ -11,4 +11,7 @@
 source_suffix = ['.rst', '.md']
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'rst/index'
+
+# The spelling list filename.
+spelling_word_list_filename=['spelling/spelling_wordlist.txt']
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/rst/appendixes/glossary.rst b/docs/rst/appendixes/glossary.rst
@@ -0,0 +1,25 @@
+
+.. _glossary:
+
+########
+Glossary
+########
+
+.. glossary::
+
+    Terrain
+        2D matrix of integers representing the height of a map at each cell.
+
+    Coordinate
+        A tuple of two integers ``(x,y)`` representing a cell in the terrain.
+
+    Path
+        A list of coordinates in the terrain.
+        To be correct, it must start in the origin, end in the destination, and each step must be adjacent to the previous one.
+
+    Cost
+        An integer number related with a path.
+        It represents a measure of the cost of the path in steps and climbs.
+
+    Path Finding Algorithm
+        A function that receives a terrain and returns a valid path.
diff --git a/docs/src/elements/generation.rst → docs/rst/elements/generation.rst b/docs/src/elements/generation.rst → docs/rst/elements/generation.rst
diff --git a/docs/src/elements/measure.rst → docs/rst/elements/measure.rst b/docs/src/elements/measure.rst → docs/rst/elements/measure.rst
diff --git a/docs/src/elements/terrain.rst → docs/rst/elements/terrain.rst b/docs/src/elements/terrain.rst → docs/rst/elements/terrain.rst
diff --git a/docs/src/installation.rst → docs/rst/getting_started/installation.rst b/docs/src/installation.rst → docs/rst/getting_started/installation.rst
@@ -1,4 +1,4 @@
-.. _installation:
+.. _getting_started_installation:
 
 ############
 Installation
@@ -10,7 +10,7 @@ Installation
 Google Colab
 ============
 
-Using :ref:`Google Colab <https://colab.google>` is the easiest way to get started.
+Using `Google Colab <https://colab.google>`_ is the easiest way to get started.
 Just add in the first cell of your notebook:
 
 .. code-block:: python
@@ -31,7 +31,7 @@ Install in Windows Anaconda
 In order to install the package in Windows Anaconda, the steps are the same as for :ref:`installation_googlecolab`.
 The only detail is that ``git`` may not be installed by default in Anaconda.
 
-From a command prompt, you can install it in a conda environment inside Anaconda:
+From a command prompt, you can install it in a ``conda`` environment inside Anaconda:
 
 .. code-block:: bash
 

diff --git a/docs/src/tldr.rst → docs/rst/getting_started/tldr.rst b/docs/src/tldr.rst → docs/rst/getting_started/tldr.rst
@@ -1,4 +1,4 @@
-.. _tldr:
+.. _getting_started_tldr:
 
 #####
 TL;DR
@@ -12,9 +12,9 @@ This project helps you to generate 2D terrains, that are matrix of integers, wit
 Over these terrains you have several features:
 
 - You can print it in the console
-- You can plot it in a matplotlib 2D plot
+- You can plot it in a ``matplotlib`` 2D plot
 - You can plot it in 3D with different angles
-- **You can check the total path of a given path**
+- **You can check the total length of a given path from origin to destination**
 - You can even draw the paths in the plots previously mentioned
 
 
@@ -28,7 +28,7 @@ Just use the following command in your notebook:
 
     !pip install git+https://github.com/jparisu/sIArena.git
 
-Check the :ref:`installation guide <installation>` for more details.
+Check the :ref:`installation guide <getting_started_installation>` for more details.
 
 
 =========================

diff --git a/docs/src/tutorial.rst → docs/rst/getting_started/tutorial.rst b/docs/src/tutorial.rst → docs/rst/getting_started/tutorial.rst
@@ -1,4 +1,4 @@
-.. _tutorial:
+.. _getting_started_tutorial:
 
 ########
 Tutorial

diff --git a/docs/rst/index.rst b/docs/rst/index.rst
@@ -0,0 +1,35 @@
+
+.. toctree::
+   :caption: Introduction
+   :maxdepth: 2
+   :hidden:
+
+   /rst/titlepage
+
+
+.. toctree::
+   :caption: Getting Started
+   :maxdepth: 2
+   :hidden:
+
+   /rst/getting_started/installation
+   /rst/getting_started/tutorial
+   /rst/getting_started/tldr
+
+
+.. toctree::
+   :caption: Elements
+   :maxdepth: 2
+   :hidden:
+
+   /rst/elements/terrain
+   /rst/elements/measure
+   /rst/elements/generation
+
+
+.. toctree::
+   :caption: Appendixes
+   :maxdepth: 2
+   :hidden:
+
+   /rst/appendixes/glossary
diff --git a/docs/src/titlepage.rst → docs/rst/titlepage.rst b/docs/src/titlepage.rst → docs/rst/titlepage.rst
@@ -32,4 +32,7 @@ This library is mainly written in *Python*.
 Further reading
 ===============
 
-To start using the library, please check the :ref:`getting_started` section.
+To start using the library, please check the following links:
+
+- :ref:`getting_started_installation`
+- :ref:`getting_started_tutorial`
diff --git a/docs/spelling/spelling_wordlist.txt b/docs/spelling/spelling_wordlist.txt
@@ -0,0 +1,2 @@
+IArena
+Colab
diff --git a/docs/src/elements/elements.rst b/docs/src/elements/elements.rst