From 22af8ce954b102434296a4563b4596d0b1a0dc94 Mon Sep 17 00:00:00 2001 From: JRoot Junior Date: Sat, 12 Aug 2023 00:59:43 +0300 Subject: [PATCH 1/4] Added Sphinx documentation for the project --- aiogram_i18n/cores/base.py | 13 +++- docs/Makefile | 20 ++++++ docs/_static/stylesheets/extra.css | 12 ++++ docs/backends/base.rst | 8 +++ docs/backends/fluent_compile.rst | 9 +++ docs/backends/fluent_runtime.rst | 9 +++ docs/backends/gettext.rst | 9 +++ docs/backends/index.rst | 109 +++++++++++++++++++++++++++++ docs/conf.py | 33 +++++++++ docs/index.rst | 95 +++++++++++++++++++++++++ docs/make.bat | 35 +++++++++ docs/poem.rst | 33 +++++++++ pyproject.toml | 6 ++ 13 files changed, 389 insertions(+), 2 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/_static/stylesheets/extra.css create mode 100644 docs/backends/base.rst create mode 100644 docs/backends/fluent_compile.rst create mode 100644 docs/backends/fluent_runtime.rst create mode 100644 docs/backends/gettext.rst create mode 100644 docs/backends/index.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/poem.rst diff --git a/aiogram_i18n/cores/base.py b/aiogram_i18n/cores/base.py index 8fbd1ac..623bb59 100644 --- a/aiogram_i18n/cores/base.py +++ b/aiogram_i18n/cores/base.py @@ -12,16 +12,25 @@ class BaseCore(Generic[Translator], ABC): + """ + Is an abstract base class for implementing core functionality for translation. + """ + default_locale: Optional[str] locales: Dict[str, Translator] def __init__(self, default_locale: Optional[str] = None) -> None: + """ + + :param default_locale: The default locale to be used for translations. + If not provided, it will default to None. + """ self.default_locale = default_locale self.locales = {} @abstractmethod def get(self, key: str, /, locale: str, **kwargs: Any) -> str: - ... + pass def get_translator(self, locale: str) -> Translator: if locale not in self.locales: @@ -74,7 +83,7 @@ def _find_locales( @abstractmethod def find_locales(self) -> Dict[str, Translator]: - ... + pass @property def available_locales(self) -> Tuple[str, ...]: diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/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 = . +BUILDDIR = _build + +# 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) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/stylesheets/extra.css b/docs/_static/stylesheets/extra.css new file mode 100644 index 0000000..b35d291 --- /dev/null +++ b/docs/_static/stylesheets/extra.css @@ -0,0 +1,12 @@ +@font-face { + font-family: 'JetBrainsMono'; + src: url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff2/JetBrainsMono-Regular.woff2') format('woff2'), + url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff/JetBrainsMono-Regular.woff') format('woff'), + url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/ttf/JetBrainsMono-Regular.ttf') format('truetype'); + font-weight: 400; + font-style: normal; +} + +code, kbd, pre { + font-family: "JetBrainsMono", "Roboto Mono", "Courier New", Courier, monospace; +} diff --git a/docs/backends/base.rst b/docs/backends/base.rst new file mode 100644 index 0000000..8699852 --- /dev/null +++ b/docs/backends/base.rst @@ -0,0 +1,8 @@ +==================== +Writing own backends +==================== + +.. automodule:: aiogram_i18n.cores.base.BaseCore + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/backends/fluent_compile.rst b/docs/backends/fluent_compile.rst new file mode 100644 index 0000000..1c64ecd --- /dev/null +++ b/docs/backends/fluent_compile.rst @@ -0,0 +1,9 @@ +============== +Fluent_compile +============== + +.. autoclass:: aiogram_i18n.cores.fluent_compile_core.FluentCompileCore + :members: + :undoc-members: + :show-inheritance: + :inherited-members: diff --git a/docs/backends/fluent_runtime.rst b/docs/backends/fluent_runtime.rst new file mode 100644 index 0000000..e9517fa --- /dev/null +++ b/docs/backends/fluent_runtime.rst @@ -0,0 +1,9 @@ +============== +Fluent.runtime +============== + +.. autoclass:: aiogram_i18n.cores.fluent_runtime_core.FluentRuntimeCore + :members: + :undoc-members: + :show-inheritance: + :inherited-members: diff --git a/docs/backends/gettext.rst b/docs/backends/gettext.rst new file mode 100644 index 0000000..9221ee9 --- /dev/null +++ b/docs/backends/gettext.rst @@ -0,0 +1,9 @@ +=========== +GLU Gettext +=========== + +.. autoclass:: aiogram_i18n.cores.gnu_text_core.GNUTextCore + :members: + :undoc-members: + :show-inheritance: + :inherited-members: diff --git a/docs/backends/index.rst b/docs/backends/index.rst new file mode 100644 index 0000000..cade52a --- /dev/null +++ b/docs/backends/index.rst @@ -0,0 +1,109 @@ +.. _Backends: + +======== +Backends +======== + +`aiogram-i18n` supports many backends of translation and localization systems, +so you can use any of them to localize your bot. + +Fluent runtime +============== + +`Fluent.runtime `_ is a part of Project Fluent, +which is a localization system developed by Mozilla for natural-sounding translations. +It's designed to unleash the expressive power of the natural language. + +If you want to use Fluent it's recommended to use `fluent_compile` instead of runtime +as it's the most efficient way to use Fluent in Python. + +Pros of using fluent.runtime +---------------------------- + +- Fluent leverages Unicode and handles complex grammatical cases and gender. +- It works on a wide range of platforms and operating systems. +- The fluent syntax is very readable which makes it easier for localizers to understand. +- It handles placeholders and markup with ease. + +Cons of using fluent.runtime +---------------------------- + +- Fluent.runtime is still young compared to gettext, therefore the community and +support aren’t as extensive. +- Its complexity and design may be way above what small projects need. + +fluent.runtime +====================== + +.. code-block:: bash + + pip install aiogram-i18n[runtime] + +Fluent compile +============== + +`fluent-compiler `_ is a Python implementation +of Project Fluent, a localization framework designed to unleash the entire expressive +power of natural language translations. + +it is mainly used to compile FTL files to AST (Abstract Syntax Tree). +It is very useful for run-time parsing. + +Pros of using fluent-compiler +----------------------------- + +- It's beneficial for handling FTL files on the runtime and compiling them into AST for efficient use. + +Cons of using fluent-compiler +----------------------------- + +- As with Fluent.runtime, fluent-compiler is relatively new and as such doesn't have +as extensive resources or community. + +Install fluent-compiler +----------------------- + +.. code-block:: bash + + pip install aiogram-i18n[compiler] + + +GNU gettext +=========== + +`GNU gettext `_ is an +internationalization (i18n) and localization (l10n) framework commonly used in open +source projects. It works by providing string function calls in your code that wraps strings +meant for user interface, and then it generates .po files which are human-readable and editable, +containing the actual translations. + +Pros of using GNU gettext +------------------------- + +- Gettext is widely used and has a large community. It means there are many tools, +guides and supports available for it. +- Offers good support for plurals. +- It handles the translation outside of your code which makes your code cleaner. +- Gettext is part of the GNU Project, being present in most of the Linux Distros. + +Cons of using GNU gettext +------------------------- + +- It can be more difficult to provide context for your strings, because the only context +you can give for your source strings are comments in your code. +- Its complexity can be intimidating for non-technical translators. + +Install GNU gettext +------------------- + +.. code-block:: bash + + pip install aiogram-i18n[gettext] + + +.. toctree:: + + fluent_compile + fluent_runtime + gettext + base diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..cb524be --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,33 @@ +# 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 +import aiogram_i18n + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "aiogram-i18n" +copyright = "2023, RootShinobi" +author = "RootShinobi" +release = aiogram_i18n.__version__ + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.viewcode", + "sphinx.ext.autodoc", +] + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "furo" +html_static_path = ["_static"] +html_css_files = [ + "stylesheets/extra.css", +] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..f22833a --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,95 @@ +======================================== +Welcome to aiogram-i18n's documentation! +======================================== + + +.. image:: https://img.shields.io/pypi/v/aiogram-i18n.svg + :target: https://pypi.python.org/pypi/aiogram-i18n + + +.. image:: https://img.shields.io/pypi/pyversions/aiogram-i18n.svg + + +.. image:: https://img.shields.io/pypi/l/aiogram-i18n.svg + + +.. image:: https://img.shields.io/pypi/dm/aiogram-i18n.svg + + +.. image:: + https://readthedocs.org/projects/aiogram-i18n/badge/?version=latest + :target: https://aiogram-i18n.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status + + +**aiogram_i18n**, an unrivalled middleware for Telegram bot internationalization, +breathes life into bots, enabling diverse interactions in multiple languages, +while adeptly managing user context, paving the way for a truly engaging and +immersive user experience irrespective of language preference, and providing robust +support for both Fluent and GNU gettext localization systems, +thereby offering flexibility in translation file format selection, +streamlining the translation process, and making the creation of multilingual bots +an achievable goal for developers. + +Installation +============ + +To install aiogram-i18n without any backends: + +.. code-block:: bash + + pip install aiogram-i18n + +If you need help with what backend to choose, read :ref:`Backends`. + + +To use FluentCompileCore +------------------------ + +To use `fluent-compiler `_ backend +(:class:`aiogram_i18n.cores.fluent_compile_core.FluentCompileCore`) install it: + +.. code-block:: bash + + pip install aiogram-i18n[compiler] + +To use FluentRuntimeCore +------------------------ + +To use `Fluent.runtime `_ backend +(:class:`aiogram_i18n.cores.fluent_runtime_core.FluentRuntimeCore`) install it: + +.. code-block:: bash + + pip install aiogram-i18n[runtime] + +To use GNU gettext +------------------ + +To use `gettext `_ backend +(:class:`aiogram_i18n.cores.gnu_text_core.py.GettextCore`) install it: + +.. code-block:: bash + + pip install aiogram-i18n[gettext] + +Usage example +============= + +.. literalinclude:: ../examples/mre.py + :language: python + :linenos: + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + +.. toctree:: + :caption: Contents: + + backends/index + poem diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..954237b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +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/poem.rst b/docs/poem.rst new file mode 100644 index 0000000..e5a839c --- /dev/null +++ b/docs/poem.rst @@ -0,0 +1,33 @@ +==== +Poem +==== + +.. code-block:: text + + In the Realm of Bots where languages intertwine, + aiogram_i18n stands tall, a beacon so divine. + Breathes life into bots, with interaction versatile, + Engaging users via tongues, in a manner user-tile. + + A supportive cradle for advanced localization, + Adept in context maintenance, rid of complications. + Promises an alluring experience, quite immersive, + For every bot user, without being non-permissive. + + Expand your bot's reach in the world's symphony, + With the power of aiogram_i18n's harmony. + Supports Fluent, gettext, the localization duet, + Increasing your bot's range, on that you can bet. + + Choose a translation file format with adaptability, + Multilingual bots are no more a liability. + Two systems supported, the translation's a smoother sail, + In the multilingual bot creation, aiogram_i18n unveils. + + Harness the strength of both, boost your bot's appeal, + Localization's no longer a task in ordeal. + Our beloved developers, lend an ear and a half, + With aiogram_i18n, give your bot users a reason to laugh. + + + *by JetBrains AI Assistant* diff --git a/pyproject.toml b/pyproject.toml index 2e7273c..f76703f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -72,6 +72,11 @@ dev = [ "pre-commit~=3.3.3", "packaging~=23.0", ] +docs = [ + "sphinx~=7.1.2", + "furo~=2023.7.26", + "sphinx-autobuild~=2021.3.14", +] [tool.hatch.envs.dev] post-install = [ @@ -83,6 +88,7 @@ features = [ "runtime", "dev", "test", + "docs", ] [tool.hatch.envs.default.scripts] From 3e87a1f2ac9cd464d6f5b452a343bef550d9e50d Mon Sep 17 00:00:00 2001 From: JRoot Junior Date: Sat, 2 Dec 2023 01:53:26 +0200 Subject: [PATCH 2/4] Fixed typo --- docs/backends/gettext.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backends/gettext.rst b/docs/backends/gettext.rst index 9221ee9..33edf14 100644 --- a/docs/backends/gettext.rst +++ b/docs/backends/gettext.rst @@ -1,5 +1,5 @@ =========== -GLU Gettext +GNU Gettext =========== .. autoclass:: aiogram_i18n.cores.gnu_text_core.GNUTextCore From 4b16381450d7f83e43a593f53270713ab7833263 Mon Sep 17 00:00:00 2001 From: JRoot Junior Date: Sat, 2 Dec 2023 02:26:44 +0200 Subject: [PATCH 3/4] Update dependencies --- pyproject.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 57ebbf9..2a9adac 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -72,8 +72,8 @@ dev = [ "packaging~=23.0", ] docs = [ - "sphinx~=7.1.2", - "furo~=2023.7.26", + "sphinx~=7.2.6", + "furo~=2023.9.10", "sphinx-autobuild~=2021.3.14", ] From ae9ecadec9c116f0684b197bb006f034a915ddf6 Mon Sep 17 00:00:00 2001 From: JRoot Junior Date: Sat, 2 Dec 2023 02:31:29 +0200 Subject: [PATCH 4/4] Added RTD config --- .readthedocs.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .readthedocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..edb99f8 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,14 @@ +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.11" + jobs: + post_install: + - pip install .[compiler,runtime,docs] + +sphinx: + configuration: docs/conf.py + +formats: all