From 08b51dddfa2104a35a4536c263c324e898c2e2d5 Mon Sep 17 00:00:00 2001 From: Kazuya Takei Date: Sat, 23 Mar 2024 20:12:41 +0900 Subject: [PATCH] doc: Write installation and small usage --- CHANGES.rst | 4 --- doc/Makefile | 5 +++- doc/changelogs/index.rst | 13 ++++++++++ doc/conf.py | 1 + doc/index.rst | 23 ++++++----------- doc/usage/index.rst | 15 +++++++++++ doc/usage/setup.rst | 55 ++++++++++++++++++++++++++++++++++++++++ pyproject.toml | 2 ++ requirements-dev.lock | 14 ++++++++++ 9 files changed, 112 insertions(+), 20 deletions(-) create mode 100644 doc/changelogs/index.rst create mode 100644 doc/usage/index.rst create mode 100644 doc/usage/setup.rst diff --git a/CHANGES.rst b/CHANGES.rst index 29ab530..847dfa2 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,7 +1,3 @@ -=========== -Change logs -=========== - v0.0.0 ====== diff --git a/doc/Makefile b/doc/Makefile index d4bb2cb..6e3f0ec 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -12,7 +12,10 @@ BUILDDIR = _build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile dev + +dev: + sphinx-autobuild -b dirhtml $(SOURCEDIR) $(BUILDDIR)/dirhtml $(O) # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/doc/changelogs/index.rst b/doc/changelogs/index.rst new file mode 100644 index 0000000..b644bbd --- /dev/null +++ b/doc/changelogs/index.rst @@ -0,0 +1,13 @@ +========== +Changelogs +========== + +.. include:: ../../CHANGES.rst + +.. toctree:: + :glob: + :reversed: + :maxdepth: 1 + :caption: Old changes + + * diff --git a/doc/conf.py b/doc/conf.py index 34d5283..0ba9e97 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -9,6 +9,7 @@ # -- General configuration extensions = [ "sphinx.ext.todo", + "sphinx_tabs.tabs", ] templates_path = ["_templates"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] diff --git a/doc/index.rst b/doc/index.rst index e5418d6..b1e702e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,22 +2,15 @@ atsphinx-mini18n ================ -Overview -======== - -.. todo:: Write it - -Installation -============ +.. toctree:: + :maxdepth: 1 -.. todo:: Write it + usage/index + changelogs/index -Usage -===== - -.. todo:: Write it +Overview +======== -Configuration -============= +This is sphinx extension to build simple i18n website. -.. todo:: Write it +It is useful to deploy documentation into single deployment entrypoint (ex: GitHub Pages). diff --git a/doc/usage/index.rst b/doc/usage/index.rst new file mode 100644 index 0000000..07d09f1 --- /dev/null +++ b/doc/usage/index.rst @@ -0,0 +1,15 @@ +===== +Usage +===== + +Please read to use ``atsphinx-mini18n`` on your documentation. + +.. warning:: + + This might not work with old Sphinx. + +.. toctree:: + :maxdepth: 2 + :caption: Contents + + setup diff --git a/doc/usage/setup.rst b/doc/usage/setup.rst new file mode 100644 index 0000000..59e12e9 --- /dev/null +++ b/doc/usage/setup.rst @@ -0,0 +1,55 @@ +===== +Setup +===== + +To first build, you should runs two step. + +Install +======= + +.. warning:: After publish first version package. + +This is published on PyPI. +You can install by ``pip`` command or your package management tools. + +.. tabs:: + + .. tab:: pip-command + + .. code:: console + + pip install atsphinx-mini18n + + .. tab:: pyproject.toml + + .. code:: toml + + [project] + dependencies = [ + "atsphinx-mini18n", + ] + +Configuration +============= + +At first, register extension into your ``conf.py`` of documentation. + +.. code-block:: python + :name: conf.py + + extensions = [ + "atsphinx.mini18n", + ] + +First build +=========== + +After setup, documentation has new builder ``i18n-html`` and ``i18n-dirhtml``. + +Please build document by new builders. + +.. code:: console + + $ make i18n-html + $ ls _build/i18n-html + index.html en diff --git a/pyproject.toml b/pyproject.toml index d872f33..c40d79d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,6 +41,8 @@ managed = true dev-dependencies = [ "pytest ==7.*", "esbonio~=0.16.4", + "sphinx-tabs~=3.4.5", + "sphinx-autobuild~=2021.3.14", ] [tool.rye.scripts] diff --git a/requirements-dev.lock b/requirements-dev.lock index 02d5a2d..29a042a 100644 --- a/requirements-dev.lock +++ b/requirements-dev.lock @@ -22,8 +22,11 @@ certifi==2024.2.2 # via requests charset-normalizer==3.3.2 # via requests +colorama==0.4.6 + # via sphinx-autobuild docutils==0.20.1 # via sphinx + # via sphinx-tabs esbonio==0.16.4 exceptiongroup==1.2.0 # via cattrs @@ -38,6 +41,8 @@ iniconfig==2.0.0 # via pytest jinja2==3.1.3 # via sphinx +livereload==2.6.3 + # via sphinx-autobuild lsprotocol==2023.0.1 # via pygls markupsafe==2.1.5 @@ -53,6 +58,7 @@ pygls==1.3.0 # via esbonio pygments==2.17.2 # via sphinx + # via sphinx-tabs pyspellchecker==0.8.1 # via esbonio pytest==7.4.4 @@ -60,11 +66,17 @@ pytz==2024.1 # via babel requests==2.31.0 # via sphinx +six==1.16.0 + # via livereload snowballstemmer==2.2.0 # via sphinx sphinx==7.1.2 # via atsphinx-mini18n # via esbonio + # via sphinx-autobuild + # via sphinx-tabs +sphinx-autobuild==2021.3.14 +sphinx-tabs==3.4.5 sphinxcontrib-applehelp==1.0.4 # via sphinx sphinxcontrib-devhelp==1.0.2 @@ -79,6 +91,8 @@ sphinxcontrib-serializinghtml==1.1.5 # via sphinx tomli==2.0.1 # via pytest +tornado==6.4 + # via livereload typing-extensions==4.10.0 # via cattrs urllib3==2.2.1