mirror of
https://github.com/searxng/searxng.git
synced 2025-10-17 03:50:37 -04:00
[enh] docs: update information (#5185)
README should be concise, everything else goes to CONTRIBUTING, docs page ...
This commit is contained in:
Ivan Gabaldon
GitHub
parent
905b13aa7e
commit
57b74beeea
@ -1,49 +0,0 @@
|
|||||||
# How to contribute
|
|
||||||
|
|
||||||
## Resources in the documentation
|
|
||||||
|
|
||||||
* [Development quickstart](https://docs.searxng.org/dev/quickstart.html)
|
|
||||||
* [Contribution guide](https://docs.searxng.org/dev/contribution_guide.html)
|
|
||||||
|
|
||||||
## Submitting PRs
|
|
||||||
|
|
||||||
Please follow the provided PR template when writing a description for your changes.
|
|
||||||
|
|
||||||
Do not take criticism personally. When you get feedback, it is about your work,
|
|
||||||
not your character, personality, etc. Keep in mind we all want to make the project better.
|
|
||||||
|
|
||||||
When something is not clear, please ask questions to clear things up.
|
|
||||||
|
|
||||||
If you would like to introduce a big architectural changes or do a refactoring
|
|
||||||
either in the codebase or the development tools, please open an issue with a proposal
|
|
||||||
first. This way we can think together about the problem and probably come up
|
|
||||||
with a better solution.
|
|
||||||
|
|
||||||
## Coding conventions and guidelines
|
|
||||||
|
|
||||||
### Commit messages
|
|
||||||
|
|
||||||
* Always write descriptive commit messages ("fix bug" is not acceptable).
|
|
||||||
* Use the present tense ("Add feature" not "Added feature").
|
|
||||||
* Use the imperative mood ("Move cursor to..." not "Moves cursor to...").
|
|
||||||
* Limit the first line to 72 characters or less.
|
|
||||||
* Include the number of the issue you are fixing.
|
|
||||||
|
|
||||||
### Coding guidelines
|
|
||||||
|
|
||||||
As a Python project, we must follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) and [PEP 20](https://www.python.org/dev/peps/pep-0020/) guidelines.
|
|
||||||
|
|
||||||
Furthermore, follow the Clean code conventions. The most important
|
|
||||||
in this project are the following rules:
|
|
||||||
|
|
||||||
* Simpler is better. [KISS principle](https://en.wikipedia.org/wiki/KISS_principle)
|
|
||||||
* Be consistent.
|
|
||||||
* Every function must do one thing.
|
|
||||||
* Use descriptive names for functions and variables.
|
|
||||||
* Always look for the root cause.
|
|
||||||
* Keep configurable data high level.
|
|
||||||
* Avoid negative conditionals.
|
|
||||||
* Prefer fewer arguments.
|
|
||||||
* Do not add obvious comment to code.
|
|
||||||
* Do not comment out code, just delete lines.
|
|
||||||
|
|
||||||
92
CONTRIBUTING.rst
Normal file
92
CONTRIBUTING.rst
Normal file
@ -0,0 +1,92 @@
|
|||||||
|
.. SPDX-License-Identifier: AGPL-3.0-or-later
|
||||||
|
|
||||||
|
.. _Quickstart guide: https://docs.searxng.org/dev/quickstart.html
|
||||||
|
.. _Commits guide: https://docs.searxng.org/dev/commits.html
|
||||||
|
.. _Weblate: https://translate.codeberg.org/projects/searxng/searxng/
|
||||||
|
.. _GitHub Codespaces: https://docs.github.com/en/codespaces/overview
|
||||||
|
.. _120 hours per month: https://github.com/settings/billing
|
||||||
|
.. _list of existing Codespaces: https://github.com/codespaces
|
||||||
|
|
||||||
|
Thank you for your interest in SearXNG.
|
||||||
|
|
||||||
|
Have a look at our `Quickstart guide`_, it's very easy to contribute.
|
||||||
|
|
||||||
|
Further information on *how-to* can be found
|
||||||
|
`here <https://docs.searxng.org/dev/index.html>`_.
|
||||||
|
|
||||||
|
Translations
|
||||||
|
============
|
||||||
|
|
||||||
|
Help translate SearXNG at `Weblate`_.
|
||||||
|
|
||||||
|
.. image:: https://translate.codeberg.org/widget/searxng/searxng/horizontal-auto.svg
|
||||||
|
:target: https://translate.codeberg.org/engage/searxng/
|
||||||
|
:alt: Weblate
|
||||||
|
:width: 768px
|
||||||
|
|
||||||
|
Cloud development
|
||||||
|
=================
|
||||||
|
|
||||||
|
You can contribute from your browser using `GitHub Codespaces`_:
|
||||||
|
|
||||||
|
- Fork the repository.
|
||||||
|
- Click on the ``<> Code`` green button.
|
||||||
|
- Click on the ``Codespaces`` tab instead of ``Local``.
|
||||||
|
- Click on ``Create codespace on master``.
|
||||||
|
- VSCode is going to start in the browser.
|
||||||
|
- Wait for ``git pull && make install`` to appear and then disappear.
|
||||||
|
- You have `120 hours per month`_ (see also your `list of existing Codespaces`_).
|
||||||
|
- You can start SearXNG using ``make run`` in the terminal or by pressing ``Ctrl+Shift+B``.
|
||||||
|
|
||||||
|
How-to contribute
|
||||||
|
=================
|
||||||
|
|
||||||
|
Submitting pull requests
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Please follow the provided PR template when writing a description for your
|
||||||
|
changes.
|
||||||
|
|
||||||
|
Do not take criticism personally. When you get feedback, it is about your work,
|
||||||
|
not your character or personality. Keep in mind we all want to make SearXNG
|
||||||
|
better.
|
||||||
|
|
||||||
|
When something is not clear, please ask questions to clear things up.
|
||||||
|
|
||||||
|
If you would like to introduce a big architectural change or do a refactor,
|
||||||
|
either in the codebase or the development tooling, please open an issue with a
|
||||||
|
proposal first. This way we can think together about the problem and probably
|
||||||
|
come up with a better solution.
|
||||||
|
|
||||||
|
Coding conventions and guidelines
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
Commit messages
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
- Always write descriptive commit messages *("fix bug" is not acceptable)*.
|
||||||
|
- Use the present tense *("Add feature", not "Added feature")*.
|
||||||
|
- Use the imperative mood *("Move cursor to...", not "Moves cursor to...")*.
|
||||||
|
- Limit the first line (commit title) to 72 characters or less.
|
||||||
|
|
||||||
|
See `Commits guide`_ for more details.
|
||||||
|
|
||||||
|
Coding guidelines
|
||||||
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
As a Python project, we must follow `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_
|
||||||
|
and `PEP 20 <https://www.python.org/dev/peps/pep-0020/>`_ guidelines.
|
||||||
|
|
||||||
|
Furthermore, follow Clean Code conventions. The most important
|
||||||
|
rules in this project are:
|
||||||
|
|
||||||
|
- Simpler is better. `KISS principle <https://en.wikipedia.org/wiki/KISS_principle>`_
|
||||||
|
- Be consistent.
|
||||||
|
- Every function must do one thing.
|
||||||
|
- Use descriptive names for functions and variables.
|
||||||
|
- Always look for the root cause.
|
||||||
|
- Keep configurable data high level.
|
||||||
|
- Avoid negative conditionals.
|
||||||
|
- Prefer fewer arguments.
|
||||||
|
- Do not add obvious comments to code.
|
||||||
|
- Do not comment out code, delete lines instead.
|
||||||
139
README.rst
139
README.rst
@ -1,130 +1,65 @@
|
|||||||
.. SPDX-License-Identifier: AGPL-3.0-or-later
|
.. SPDX-License-Identifier: AGPL-3.0-or-later
|
||||||
|
|
||||||
----
|
.. _metasearch engine: https://en.wikipedia.org/wiki/Metasearch_engine
|
||||||
|
.. _Installation guide: https://docs.searxng.org/admin/installation.html
|
||||||
|
.. _Configuration guide: https://docs.searxng.org/admin/settings/index.html
|
||||||
|
.. _CONTRIBUTING: https://raw.githubusercontent.com/searxng/searxng/refs/heads/master/CONTRIBUTING.rst
|
||||||
|
.. _LICENSE: https://raw.githubusercontent.com/searxng/searxng/refs/heads/master/LICENSE
|
||||||
|
|
||||||
.. figure:: https://raw.githubusercontent.com/searxng/searxng/master/client/simple/src/brand/searxng.svg
|
.. figure:: https://raw.githubusercontent.com/searxng/searxng/master/client/simple/src/brand/searxng.svg
|
||||||
:target: https://docs.searxng.org/
|
:target: https://searxng.org
|
||||||
:alt: SearXNG
|
:alt: SearXNG
|
||||||
:width: 100%
|
:width: 512px
|
||||||
:align: center
|
|
||||||
|
|
||||||
----
|
|
|
||||||
|
|
||||||
Privacy-respecting, hackable `metasearch engine`_
|
SearXNG is a `metasearch engine`_. Users are neither tracked nor profiled.
|
||||||
|
|
||||||
Searx.space_ lists ready-to-use running instances.
|
.. image:: https://img.shields.io/badge/organization-3050ff?style=flat-square&logo=searxng&logoColor=fff&cacheSeconds=86400
|
||||||
|
:target: https://github.com/searxng
|
||||||
|
:alt: Organization
|
||||||
|
|
||||||
A user_, admin_ and developer_ handbook is available on the homepage_.
|
.. image:: https://img.shields.io/badge/documentation-3050ff?style=flat-square&logo=readthedocs&logoColor=fff&cacheSeconds=86400
|
||||||
|
:target: https://docs.searxng.org
|
||||||
|
:alt: Documentation
|
||||||
|
|
||||||
|SearXNG install|
|
.. image:: https://img.shields.io/github/license/searxng/searxng?style=flat-square&label=license&color=3050ff&cacheSeconds=86400
|
||||||
|SearXNG homepage|
|
:target: https://raw.githubusercontent.com/searxng/searxng/refs/heads/master/LICENSE
|
||||||
|SearXNG wiki|
|
:alt: License
|
||||||
|AGPL License|
|
|
||||||
|Issues|
|
|
||||||
|commits|
|
|
||||||
|weblate|
|
|
||||||
|SearXNG logo|
|
|
||||||
|
|
||||||
----
|
.. image:: https://img.shields.io/github/commit-activity/y/searxng/searxng/master?style=flat-square&label=commits&color=3050ff&cacheSeconds=3600
|
||||||
|
:target: https://github.com/searxng/searxng/commits/master/
|
||||||
|
:alt: Commits
|
||||||
|
|
||||||
.. _searx.space: https://searx.space
|
.. image:: https://img.shields.io/weblate/progress/searxng?server=https%3A%2F%2Ftranslate.codeberg.org&style=flat-square&label=translated&color=3050ff&cacheSeconds=86400
|
||||||
.. _user: https://docs.searxng.org/user
|
|
||||||
.. _admin: https://docs.searxng.org/admin
|
|
||||||
.. _developer: https://docs.searxng.org/dev
|
|
||||||
.. _homepage: https://docs.searxng.org/
|
|
||||||
.. _metasearch engine: https://en.wikipedia.org/wiki/Metasearch_engine
|
|
||||||
|
|
||||||
.. |SearXNG logo| image:: https://raw.githubusercontent.com/searxng/searxng/master/client/simple/src/brand/searxng-wordmark.svg
|
|
||||||
:target: https://docs.searxng.org/
|
|
||||||
:width: 5%
|
|
||||||
|
|
||||||
.. |SearXNG install| image:: https://img.shields.io/badge/-install-blue
|
|
||||||
:target: https://docs.searxng.org/admin/installation.html
|
|
||||||
|
|
||||||
.. |SearXNG homepage| image:: https://img.shields.io/badge/-homepage-blue
|
|
||||||
:target: https://docs.searxng.org/
|
|
||||||
|
|
||||||
.. |SearXNG wiki| image:: https://img.shields.io/badge/-wiki-blue
|
|
||||||
:target: https://github.com/searxng/searxng/wiki
|
|
||||||
|
|
||||||
.. |AGPL License| image:: https://img.shields.io/badge/license-AGPL-blue.svg
|
|
||||||
:target: https://github.com/searxng/searxng/blob/master/LICENSE
|
|
||||||
|
|
||||||
.. |Issues| image:: https://img.shields.io/github/issues/searxng/searxng?color=yellow&label=issues
|
|
||||||
:target: https://github.com/searxng/searxng/issues
|
|
||||||
|
|
||||||
.. |PR| image:: https://img.shields.io/github/issues-pr-raw/searxng/searxng?color=yellow&label=PR
|
|
||||||
:target: https://github.com/searxng/searxng/pulls
|
|
||||||
|
|
||||||
.. |commits| image:: https://img.shields.io/github/commit-activity/y/searxng/searxng?color=yellow&label=commits
|
|
||||||
:target: https://github.com/searxng/searxng/commits/master
|
|
||||||
|
|
||||||
.. |weblate| image:: https://translate.codeberg.org/widgets/searxng/-/searxng/svg-badge.svg
|
|
||||||
:target: https://translate.codeberg.org/projects/searxng/
|
:target: https://translate.codeberg.org/projects/searxng/
|
||||||
|
:alt: Translated
|
||||||
|
|
||||||
Contact
|
|
||||||
=======
|
|
||||||
|
|
||||||
Ask questions or chat with the SearXNG community (this not a chatbot) on
|
|
||||||
|
|
||||||
IRC
|
|
||||||
`#searxng on libera.chat <https://web.libera.chat/?channel=#searxng>`_
|
|
||||||
which is bridged to Matrix.
|
|
||||||
|
|
||||||
Matrix
|
|
||||||
`#searxng:matrix.org <https://matrix.to/#/#searxng:matrix.org>`_
|
|
||||||
|
|
||||||
|
|
||||||
Setup
|
Setup
|
||||||
=====
|
=====
|
||||||
|
|
||||||
- A well maintained `Docker image`_, also built for ARM64 and ARM/v7
|
To install SearXNG, see `Installation guide`_.
|
||||||
architectures.
|
|
||||||
- Alternatively there are *up to date* `installation scripts`_.
|
|
||||||
- For individual setup consult our detailed `Step by step`_ instructions.
|
|
||||||
- To fine-tune your instance, take a look at the `Administrator documentation`_.
|
|
||||||
|
|
||||||
.. _Administrator documentation: https://docs.searxng.org/admin/index.html
|
To fine-tune SearXNG, see `Configuration guide`_.
|
||||||
.. _Step by step: https://docs.searxng.org/admin/installation-searxng.html
|
|
||||||
.. _installation scripts: https://docs.searxng.org/admin/installation-scripts.html
|
|
||||||
.. _Docker image: https://github.com/searxng/searxng-docker
|
|
||||||
|
|
||||||
Translations
|
Further information on *how-to* can be found `here <https://docs.searxng.org/admin/index.html>`_.
|
||||||
============
|
|
||||||
|
|
||||||
.. _Weblate: https://translate.codeberg.org/projects/searxng/searxng/
|
Connect
|
||||||
|
=======
|
||||||
|
|
||||||
Help translate SearXNG at `Weblate`_
|
If you have questions or want to connect with others in the community,
|
||||||
|
we have two official channels:
|
||||||
.. figure:: https://translate.codeberg.org/widgets/searxng/-/multi-auto.svg
|
|
||||||
:target: https://translate.codeberg.org/projects/searxng/
|
|
||||||
|
|
||||||
|
- `#searxng:matrix.org <https://matrix.to/#/#searxng:matrix.org>`_
|
||||||
|
- `#searxng @ libera.chat <https://web.libera.chat/?channel=#searxng>`_ (bridged to Matrix)
|
||||||
|
|
||||||
Contributing
|
Contributing
|
||||||
============
|
============
|
||||||
|
|
||||||
.. _development quickstart: https://docs.searxng.org/dev/quickstart.html
|
See `CONTRIBUTING`_ for more details.
|
||||||
.. _developer documentation: https://docs.searxng.org/dev/index.html
|
|
||||||
|
|
||||||
Are you a developer? Have a look at our `development quickstart`_ guide, it's
|
License
|
||||||
very easy to contribute. Additionally we have a `developer documentation`_.
|
=======
|
||||||
|
|
||||||
|
This project is licensed under the GNU Affero General Public License (AGPL-3.0).
|
||||||
Codespaces
|
See `LICENSE`_ for more details.
|
||||||
==========
|
|
||||||
|
|
||||||
You can contribute from your browser using `GitHub Codespaces`_:
|
|
||||||
|
|
||||||
- Fork the repository
|
|
||||||
- Click on the ``<> Code`` green button
|
|
||||||
- Click on the ``Codespaces`` tab instead of ``Local``
|
|
||||||
- Click on ``Create codespace on master``
|
|
||||||
- VSCode is going to start in the browser
|
|
||||||
- Wait for ``git pull && make install`` to appear and then disappear
|
|
||||||
- You have `120 hours per month`_ (see also your `list of existing Codespaces`_)
|
|
||||||
- You can start SearXNG using ``make run`` in the terminal or by pressing ``Ctrl+Shift+B``
|
|
||||||
|
|
||||||
.. _GitHub Codespaces: https://docs.github.com/en/codespaces/overview
|
|
||||||
.. _120 hours per month: https://github.com/settings/billing
|
|
||||||
.. _list of existing Codespaces: https://github.com/codespaces
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user