From f09459b98ae877d7dfd40d85c0edf058c65913d5 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 18 Dec 2019 16:11:05 +0100 Subject: doc: describe Makefile targets With the aim to simplify development cycles, started with PR #1756 a Makefile based boilerplate was added. This patch adds the missing developer documentation. Signed-off-by: Markus Heiser --- docs/dev/contribution_guide.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'docs/dev/contribution_guide.rst') diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 064f28e63..6d8d3924d 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -79,6 +79,8 @@ Translation currently takes place on :ref:`transifex `. Please, do not update translation files in the repo. +.. _contrib docs: + Documentation ============= @@ -91,7 +93,7 @@ Documentation The documentation is built using Sphinx_. So in order to be able to generate the required files, you have to install it on your system. Much easier, use -Makefile our targets. +our :ref:`makefile`. Here is an example which makes a complete rebuild: @@ -101,6 +103,7 @@ Here is an example which makes a complete rebuild: ... The HTML pages are in dist/docs. +.. _make docs-live: live build ---------- @@ -110,9 +113,10 @@ live build It is recommended to assert a complete rebuild before deploying (use ``docs-clean``). -Live build is like WYSIWYG, If you want to edit the documentation, its -recommended to use. The Makefile target ``docs-live`` builds the docs, opens URL -in your favorite browser and rebuilds every time a reST file has been changed. +Live build is like WYSIWYG. If you want to edit the documentation, its +recommended to use. The Makefile target ``docs-live`` builds the docs, opens +URL in your favorite browser and rebuilds every time a reST file has been +changed. .. code:: sh @@ -123,12 +127,13 @@ in your favorite browser and rebuilds every time a reST file has been changed. ... Start watching changes +.. _deploy on github.io: deploy on github.io ------------------- To deploy documentation at :docs:`github.io <.>` use Makefile target -``gh-pages``, which will builds the documentation, clones searx into a sub +:ref:`make gh-pages`, which will builds the documentation, clones searx into a sub folder ``gh-pages``, cleans it, copies the doc build into and runs all the needed git add, commit and push: -- cgit v1.2.3 From aa3b0265e761eec07055d8f248d677a5cb4e8725 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sun, 22 Dec 2019 14:05:33 +0100 Subject: doc: add 'Architecture' article to admin section Herein we add some hints and suggestions about typical architectures of searx infrastructures. We start with a contribution from @dalf - https://github.com/asciimoo/searx/pull/1776#issuecomment-567917320 thanks @dalf !! Signed-off-by: Markus Heiser --- docs/dev/contribution_guide.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/dev/contribution_guide.rst') diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 6d8d3924d..ccc101d2e 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -1,3 +1,5 @@ +.. _how to contribute: + ================= How to contribute ================= -- cgit v1.2.3 From 4ca8b69c81ddbd965ff88deeaed7bc4f0709fbf4 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Tue, 24 Dec 2019 18:48:23 +0100 Subject: doc(dev): add remarks about creating good commits (messages) preview (don't bookmark): https://return42.github.io/searx/dev/contribution_guide.html#code Signed-off-by: Markus Heiser --- docs/dev/contribution_guide.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'docs/dev/contribution_guide.rst') diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index ccc101d2e..c6030fbe3 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -50,6 +50,16 @@ Code ==== .. _PEP8: https://www.python.org/dev/peps/pep-0008/ +.. _Conventional Commits: https://www.conventionalcommits.org/ +.. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages +.. _Structural split of changes: + https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes + +.. sidebar:: Create good commits! + + - `Structural split of changes`_ + - `Conventional Commits`_ + - `Git Commit Good Practice`_ In order to submit a patch, please follow the steps below: @@ -59,6 +69,9 @@ In order to submit a patch, please follow the steps below: - PEP8_ standards apply, except the convention of line length - Maximum line length is 120 characters +- The cardinal rule for creating good commits is to ensure there is only one + *logical change* per commit / read `Structural split of changes`_ + - Check if your code breaks existing tests. If so, update the tests or fix your code. @@ -66,6 +79,16 @@ In order to submit a patch, please follow the steps below: - Add yourself to the :origin:`AUTHORS.rst` file. +- Choose meaning full commit messages, read `Conventional Commits`_ + + .. code:: + + [optional scope]: + + [optional body] + + [optional footer(s)] + - Create a pull request. For more help on getting started with searx development, see :ref:`devquickstart`. -- cgit v1.2.3 From 62505f8982c2bc2cae5456a7ab50932fea580cc4 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 25 Dec 2019 09:57:21 +0100 Subject: docs(dev): add refs to to gitmoji and Semantic PR in contrib section preview (don't bookmark): https://return42.github.io/searx/dev/contribution_guide.html#code Signed-off-by: Markus Heiser --- docs/dev/contribution_guide.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/dev/contribution_guide.rst') diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index c6030fbe3..459dfb448 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -54,13 +54,16 @@ Code .. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages .. _Structural split of changes: https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes +.. _gitmoji: https://gitmoji.carloscuesta.me/ +.. _Semantic PR: https://github.com/zeke/semantic-pull-requests .. sidebar:: Create good commits! - `Structural split of changes`_ - `Conventional Commits`_ - `Git Commit Good Practice`_ - + - some like to use: gitmoji_ + - not yet active: `Semantic PR`_ In order to submit a patch, please follow the steps below: -- cgit v1.2.3