rinigus · magdesign · Jan 17, 2025 · Jan 19, 2025 · Jan 19, 2025 · Jan 19, 2025
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,39 @@
+name: Build Sphinx Documentation
+
+on:
+  push:
+    branches:
+      - main  # Change this to your main branch if different
+  pull_request:
+    branches:
+      - main  # Change this to your main branch if different
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.8'  # Use the Python version you need
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install sphinx 
+        pip install sphinx-rtd-theme
+
+    - name: Build HTML documentation
+      run: |
+        mkdir -p docs
+        cd docs-raw
+        sphinx docs-raw docs
+
+    - name: create nojekyll file
+      run: |
+        cd docs
+        touch .nojekyll
diff --git a/docs-raw/Makefile b/docs-raw/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = ../docs
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -b $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs-raw/make.bat b/docs-raw/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs-raw/source/_static/01_pure-maps_satelite.png b/docs-raw/source/_static/01_pure-maps_satelite.png
diff --git a/docs-raw/source/_static/03_preferences_api-key.png b/docs-raw/source/_static/03_preferences_api-key.png
diff --git a/docs-raw/source/_static/04_about_screen.png b/docs-raw/source/_static/04_about_screen.png
diff --git a/docs-raw/source/_static/04_bookmarks.png b/docs-raw/source/_static/04_bookmarks.png
diff --git a/docs-raw/source/_static/04_map_type.png b/docs-raw/source/_static/04_map_type.png
diff --git a/docs-raw/source/_static/04_maps_choice.png b/docs-raw/source/_static/04_maps_choice.png
diff --git a/docs-raw/source/_static/04_navigation.png b/docs-raw/source/_static/04_navigation.png
diff --git a/docs-raw/source/_static/04_navigation_gpx_track.png b/docs-raw/source/_static/04_navigation_gpx_track.png
diff --git a/docs-raw/source/_static/04_navigation_routing_engine.png b/docs-raw/source/_static/04_navigation_routing_engine.png
diff --git a/docs-raw/source/_static/04_overview.png b/docs-raw/source/_static/04_overview.png
diff --git a/docs-raw/source/_static/04_preferences.png b/docs-raw/source/_static/04_preferences.png
diff --git a/docs-raw/source/_static/04_profile.png b/docs-raw/source/_static/04_profile.png
diff --git a/docs-raw/source/_static/04_search.png b/docs-raw/source/_static/04_search.png
diff --git a/docs-raw/source/_static/04_share_position.png b/docs-raw/source/_static/04_share_position.png
diff --git a/docs-raw/source/_static/05_osmscout-server-gui.png b/docs-raw/source/_static/05_osmscout-server-gui.png
diff --git a/docs-raw/source/_static/05_osmscout-server-gui_menu.png b/docs-raw/source/_static/05_osmscout-server-gui_menu.png
diff --git a/docs-raw/source/conf.py b/docs-raw/source/conf.py
@@ -0,0 +1,37 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'pure-maps'
+copyright = '2025, pure-maps'
+author = 'magdesign'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+ #   'sphinx_toolbox.shields'
+]
+
+
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+import sphinx_rtd_theme
+
+html_theme = 'sphinx_rtd_theme'
+html_logo = 'logo.svg'
+html_theme_options = {
+    'logo_only': False,
+    'display_version': False,
+}
+html_static_path = ['_static']
diff --git a/docs-raw/source/faq.rst b/docs-raw/source/faq.rst
@@ -0,0 +1,21 @@
+.. _faq:
+
+FAQ
+===
+Frequently asked questions:
+
+ Can i use pure-maps offline?
+  Yes, when running :ref:`osmscout-server`  
+  Pure Maps navigates completely offline.
+  See :ref:`Offline-Navigation`  
+
+ Can I import .gpx tracks?
+  Yes, but its limited to the navigation module.
+  See :ref:`GPX-Import`  
+
+ Does Pure Maps display height profiles?
+  No.
+
+ Why can't I route long trips for walking or cycling in offline mode?
+  Increase limits in :ref:`osmscout-server`-gui in
+  ``Settings > Backend settings > Valhalla > Limits``.   
diff --git a/docs-raw/source/index.rst b/docs-raw/source/index.rst
@@ -0,0 +1,75 @@
+.. _index:
+
+Pure Maps
+=========
+
+**Pure Maps** is an application for Linux to display vector and raster
+maps, places, routes and provide navigation instructions with a
+flexible selection of data and service providers. Its designed for mobile devices. 
+
+.. image:: _static/01_pure-maps_satelite.png
+   :alt: pure-maps screenshot
+   :width: 400
+
+.. image:: https://img.shields.io/github/v/release/rinigus/pure-maps
+   :alt: Latest Release
+   :target: https://github.com/rinigus/pure-maps/releases
+
+.. image:: https://img.shields.io/badge/Ubuntu%20Touch-OpenStore-292929
+   :alt: Ubuntu Touch
+   :target: https://open-store.io/app/pure-maps.jonnius
+
+.. image:: https://img.shields.io/badge/Flatpak-Flathub-4A86CF
+   :alt: Flatpak
+   :target: https://flathub.org/apps/details/io.github.rinigus.PureMaps
+
+.. image:: https://img.shields.io/badge/O.B.S-Fedora-3C6EB4  
+   :alt: Fedora
+   :target: https://build.opensuse.org/package/show/home:rinigus:maps/pure-maps
+
+.. image:: https://img.shields.io/badge/matrix.org-%23pure--maps-blue
+   :alt: Matrix
+   :target: https://matrix.to/#/#pure-maps:matrix.org
+
+.. image:: https://img.shields.io/badge/forum-GitHub-FB9200
+   :alt: Discussions
+   :target: https://github.com/rinigus/pure-maps/discussions
+
+
+
+.. Note::
+   Add your content using ``reStructuredText`` syntax to ``docs-raw`` folder. See this `issue`_ and
+   `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+   documentation for details.
+
+.. _issue: https://github.com/rinigus/pure-maps/issues/400 
+
+
+User feedback
+--------------
+
+Use `Github Issues`_ to address specific problems and development
+requests.
+
+General discussion is expected either through corresponding
+topics in `Github Discussions`_,  `Github Issues`_ , `Matrix channel`_,
+or `TMO`_ thread. 
+
+.. _Github Issues: https://github.com/rinigus/pure-maps/issues
+
+.. _Github Discussions: https://github.com/rinigus/pure-maps/discussions
+
+.. _Matrix channel: https://matrix.to/#/#pure-maps:matrix.org
+
+.. _TMO: https://talk.maemo.org/showthread.php?t=100442
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Content
+
+   faq
+   installation
+   usage
+   osmscout-server   
+   troubleshooting
diff --git a/docs-raw/source/installation.rst b/docs-raw/source/installation.rst
@@ -0,0 +1,59 @@
+.. _installation:
+
+Installation
+==============
+
+**Linux**
+
+On most popular distributions Pure Maps can
+simply be installed via package manager. 
+
+.. image:: https://repology.org/badge/vertical-allrepos/pure-maps.svg
+   :alt: Packaging status
+   :target: https://repology.org/project/pure-maps/versions
+
+
+For example on Alpine/postmarketOS:
+
+.. code-block:: shell
+
+ sudo apk add pure-maps osmscout-server
+
+
+**Flatpak**
+
+There is a Flatpak build on `flathub`_.
+
+.. code-block:: shell
+
+ sudo flatpak install flathub io.github.rinigus.PureMaps
+ sudo flatpak install flathub io.github.rinigus.OSMScoutServer
+
+.. _flathub: https://flathub.org/apps/io.github.rinigus.PureMaps
+
+**Ubuntu Touch**
+
+Install via `open-store <https://open-store.io/app/pure-maps.jonnius>`_
+
+or the `slim version <https://open-store.io/app/pure-maps-slim.jonnius>`_ without text-to-speech
+
+
+**Sailfish**
+
+Install via `chum`_
+
+.. _chum: https://build.sailfishos.org/package/show/sailfishos:chum/pure-maps'
+
+
+.. _API_key:
+
+API Keys
+---------
+To get access to online  maps, its
+recommended to go to ``Preferences > API keys``
+and add API keys. You get them with
+registering on each linked map provider.
+
+.. image:: _static/03_preferences_api-key.png
+   :alt: api keys page
+   :width: 400