From 28ec0d513ce817540992f8798048aa7f85583071 Mon Sep 17 00:00:00 2001 From: jparisu <69341543+jparisu@users.noreply.github.com> Date: Thu, 1 Feb 2024 10:11:18 +0100 Subject: [PATCH] Add Docs test action (#1) * Add Docs test action Signed-off-by: jparisu * Fix some stuff Signed-off-by: jparisu * Fix spelling Signed-off-by: jparisu * Fix some docs stuff Signed-off-by: jparisu * Final touches Signed-off-by: jparisu --------- Signed-off-by: jparisu --- .github/workflows/docs.yml | 34 ++++++++++++++++++ docs/conf.py | 5 ++- docs/index.rst | 18 ---------- docs/rst/appendixes/glossary.rst | 25 +++++++++++++ docs/{src => rst}/elements/generation.rst | 0 docs/{src => rst}/elements/measure.rst | 0 docs/{src => rst}/elements/terrain.rst | 0 .../getting_started}/installation.rst | 6 ++-- docs/{src => rst/getting_started}/tldr.rst | 8 ++--- .../{src => rst/getting_started}/tutorial.rst | 2 +- docs/rst/index.rst | 35 +++++++++++++++++++ docs/{src => rst}/titlepage.rst | 5 ++- docs/spelling/spelling_wordlist.txt | 2 ++ docs/src/elements/elements.rst | 14 -------- 14 files changed, 112 insertions(+), 42 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 docs/index.rst create mode 100644 docs/rst/appendixes/glossary.rst rename docs/{src => rst}/elements/generation.rst (100%) rename docs/{src => rst}/elements/measure.rst (100%) rename docs/{src => rst}/elements/terrain.rst (100%) rename docs/{src => rst/getting_started}/installation.rst (84%) rename docs/{src => rst/getting_started}/tldr.rst (78%) rename docs/{src => rst/getting_started}/tutorial.rst (69%) create mode 100644 docs/rst/index.rst rename docs/{src => rst}/titlepage.rst (87%) create mode 100644 docs/spelling/spelling_wordlist.txt delete mode 100644 docs/src/elements/elements.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..6bef722 --- /dev/null +++ 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 index 3a7147f..347623a 100644 --- 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 deleted file mode 100644 index 3ab55fb..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,18 +0,0 @@ - -.. include:: src/titlepage.rst - -.. toctree:: - :caption: Project - :maxdepth: 2 - :hidden: - - /src/installation - /src/tutorial - /src/tlnr - -.. toctree:: - :caption: Elements - :maxdepth: 2 - :hidden: - - /src/elements/elements diff --git a/docs/rst/appendixes/glossary.rst b/docs/rst/appendixes/glossary.rst new file mode 100644 index 0000000..f4229ae --- /dev/null +++ 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 b/docs/rst/elements/generation.rst similarity index 100% rename from docs/src/elements/generation.rst rename to docs/rst/elements/generation.rst diff --git a/docs/src/elements/measure.rst b/docs/rst/elements/measure.rst similarity index 100% rename from docs/src/elements/measure.rst rename to docs/rst/elements/measure.rst diff --git a/docs/src/elements/terrain.rst b/docs/rst/elements/terrain.rst similarity index 100% rename from docs/src/elements/terrain.rst rename to docs/rst/elements/terrain.rst diff --git a/docs/src/installation.rst b/docs/rst/getting_started/installation.rst similarity index 84% rename from docs/src/installation.rst rename to docs/rst/getting_started/installation.rst index 2156fe6..00fcec5 100644 --- a/docs/src/installation.rst +++ b/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 ` is the easiest way to get started. +Using `Google Colab `_ 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 b/docs/rst/getting_started/tldr.rst similarity index 78% rename from docs/src/tldr.rst rename to docs/rst/getting_started/tldr.rst index b7040f0..9ab3a87 100644 --- a/docs/src/tldr.rst +++ b/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 ` for more details. +Check the :ref:`installation guide ` for more details. ========================= diff --git a/docs/src/tutorial.rst b/docs/rst/getting_started/tutorial.rst similarity index 69% rename from docs/src/tutorial.rst rename to docs/rst/getting_started/tutorial.rst index 16870c7..0fa8353 100644 --- a/docs/src/tutorial.rst +++ b/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 new file mode 100644 index 0000000..732e799 --- /dev/null +++ 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 b/docs/rst/titlepage.rst similarity index 87% rename from docs/src/titlepage.rst rename to docs/rst/titlepage.rst index 1426cde..55c5552 100644 --- a/docs/src/titlepage.rst +++ b/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 new file mode 100644 index 0000000..6d1d05b --- /dev/null +++ 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 deleted file mode 100644 index 915bffd..0000000 --- a/docs/src/elements/elements.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _elements: - -######## -Elements -######## - -.. toctree:: - :caption: Project - :maxdepth: 2 - :hidden: - - terrain - measure - generation