Achieve first ietartion on new documentation

Guts · Feb 10, 2021 · 02f79a1 · 02f79a1
1 parent 0a6e441
commit 02f79a1
Show file tree

Hide file tree

Showing 14 changed files with 89 additions and 29 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -49,9 +49,9 @@
     "sphinx.ext.extlinks",
     "sphinx.ext.viewcode",
     # 3rd party
+    "myst_parser",
     # "sphinx_autodoc_typehints",
     "sphinx_copybutton",
-    "myst_parser",
     "sphinx_rtd_theme",
 ]
 
@@ -89,8 +89,20 @@
 # html_static_path = ["_static"]
 html_theme = "sphinx_rtd_theme"
 html_theme_options = {
-    "github_url": __about__.__uri__,
-    "repository_url": __about__.__uri__,
+    # "canonical_url": __about__.__uri_homepage__,
+    "display_version": True,
+    # "github_url": __about__.__uri__,
+    "logo_only": False,
+    "prev_next_buttons_location": "both",
+    # "repository_url": __about__.__uri__,
+    "style_external_links": True,
+    "style_nav_header_background": "SteelBlue",
+    # Toc options
+    "collapse_navigation": False,
+    "includehidden": False,
+    "navigation_depth": 4,
+    "sticky_navigation": False,
+    "titles_only": False,
 }
 
 

diff --git a/docs/configuration/exclude.md b/docs/configuration/exclude.md
@@ -1,4 +1,4 @@
-# Excluding files in the plugin archive
+# Exclude files in the plugin archive
 
 If you want to avoid some files to be shipped with your plugin, create a `.gitattributes` file in which you can specify the files to ignore. For instance:
 

diff --git a/docs/configuration/options.md b/docs/configuration/options.md
@@ -0,0 +1,3 @@
+# Settings
+
+> TO DOC
diff --git a/docs/usage/submodules.md → docs/configuration/submodules.md b/docs/usage/submodules.md → docs/configuration/submodules.md
@@ -1,4 +1,4 @@
-# Submodules
+# Handle submodules
 
 If you have any submodule configured using ssh and not https, you need to change the connection url by doing:
 

diff --git a/docs/development/contribute.md b/docs/development/contribute.md
@@ -0,0 +1,3 @@
+# Contribution Guidelines
+
+> TO DOC
diff --git a/docs/development/documentation.md b/docs/development/documentation.md
@@ -18,26 +18,7 @@ Open `docs/_build/index.html` in a web browser.
 ## Write documentation using live render
 
 ```bash
-sphinx-autobuild -b html . ./_build
+sphinx-autobuild -b html docs/ docs/_build
 ```
 
 Open <http://localhost:8000> in a web browser to see the HTML render updated when a file is saved.
-
-## Add a new page to the documentation
-
-For example, to add a usage in a new language:
-
-1. Create a markdown file into `docs/usage/usage_{locale}.md` where `{locale}` is the language code (en, fr, it, sp...)
-2. Reference this new page in the homepage toctree:
-
-````markdown
-```{toctree}
----
-caption: How to use the plugin
-maxdepth: 1
----
-usage/index
-usage/usage_en
-usage/usage_fr
-```
-````
diff --git a/docs/development/environment.md b/docs/development/environment.md
@@ -9,6 +9,9 @@ Typically on Ubuntu:
 python3.8 -m venv .venv
 
 # bump dependencies inside venv
-python -m pip install -U pip
-python -m pip install -U -r requirements/development.txt
+python -m pip install -U pip setuptools wheel
+python -m pip install -U -r requirements.txt
+
+# install project as editable
+python -m pip install -e .
 ```
diff --git a/docs/development/history.md b/docs/development/history.md
@@ -0,0 +1,2 @@
+```{include} ../../CHANGELOG.md
+```
diff --git a/docs/index.md b/docs/index.md
@@ -1,4 +1,57 @@
+# {{ title }} - Documentation
 
+> **Author and contributors:** {{ author }}
+> **Version:** {{ version }}
+> **Source code:** {{ repo_url }}
+
+## Installation
+
+Package is available on [PyPi](https://pypi.org/project/qgis-plugin-ci/):
+
+```bash
+pip install qgis-plugin-ci
+```
+
+```{toctree}
+---
+caption: Configuration
+maxdepth: 1
+---
+configuration/options
+configuration/exclude
+configuration/submodules
+```
+
+```{toctree}
+---
+caption: Use in CI/CD platforms
+maxdepth: 1
+---
+usage/ci_github
+usage/ci_gitlab
+usage/ci_docker
+usage/ci_travis
+```
+
+```{toctree}
+---
+caption: Miscellaneous
+maxdepth: 1
+---
+misc/faq
+```
+
+```{toctree}
+---
+caption: Contribution guide
+maxdepth: 1
+---
+development/contribute
+development/environment
+development/documentation
+development/packaging
+development/history
+```
 
 ## Gallery
 

diff --git a/docs/installation.md b/docs/installation.md
diff --git a/docs/faq.md → docs/misc/faq.md b/docs/faq.md → docs/misc/faq.md
diff --git a/docs/usage/ci_github.md b/docs/usage/ci_github.md
@@ -1,4 +1,4 @@
-# Automatic deployment on github workflows
+# GitHub workflows
 
 qgis-plugin-ci integrates nicely with github workflows. The following example automatically uploads plugins to releases and to the plugin repository when a new release is created on github.
 

diff --git a/docs/usage/ci_gitlab.md b/docs/usage/ci_gitlab.md
@@ -0,0 +1,3 @@
+# GitLab CI
+
+> TO DOC
diff --git a/docs/usage/ci_travis.md b/docs/usage/ci_travis.md
@@ -1,4 +1,4 @@
-# Automatic deployment on Travis
+# TravisCI
 
 ## Basic configuration