diff --git a/.gitignore b/.gitignore index 3c5b2a1..e2b54de 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,12 @@ # Python +.venv/ *__pycache__* **/.pyc tmp/ -docs/build/ *.egg *.egg-info dist -build +build/ +_build/ +docs/html/ eggs \ No newline at end of file diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..4f7d909 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,19 @@ +version: 2 +build: + os: ubuntu-24.04 + tools: + python: "3.12" + +sphinx: + configuration: docs/conf.py + +python: + install: + - method: pip + path: . + extra_requirements: + - docs + +formats: + - epub + - pdf \ No newline at end of file diff --git a/README.rst b/README.rst index f8499de..6fcd8cd 100644 --- a/README.rst +++ b/README.rst @@ -1,11 +1,14 @@ cmdcraft ======== +.. image:: https://github.com/weinsen/cmdcraft/actions/workflows/unit_tests.yml/badge.svg?branch=master + :target: https://github.com/weinsen/cmdcraft/actions/workflows/unit_tests.yml + ``cmdcraft`` is a library that aims to build fast and stable -interative devtools. It that native Python metadata from objects to build prompt +interactive devtools. It uses native Python metadata from objects to build prompt commands, so you don't have to manually configure input options. -.. image:: docs/source/images/example.gif +.. image:: docs/images/example.gif Features -------- @@ -18,7 +21,13 @@ Features Contributing ============ -Contributions are welcome! Please start by reading the `Contributing Guidelines `_ file. +Contributions are welcome! Please start by reading the `Contributing Guidelines `_ file. + +License +======= + +This project is licensed under the BSD-style license found in the LICENSE file in the +root directory of this source tree. Special thanks ============== diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf..1ff5007 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,20 +1,13 @@ -# Minimal makefile for Sphinx documentation -# +PYTHON ?= python +SPHINXBUILD = $(PYTHON) -m sphinx +SPHINXAPIDOC = $(PYTHON) -m sphinx.ext.apidoc +SOURCEDIR = . +BUILDDIR = _build -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build +.PHONY: apidoc html -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +apidoc: + $(SPHINXAPIDOC) -f -e -o _generated ../src/cmdcraft -.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) +html: + $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..0248f7b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,37 @@ +"""Sphinx configuration for the cmdcraft documentation.""" + +project = "cmdcraft" +copyright = "2026, A. M. Weinsen Jr" +author = "A. M. Weinsen Jr" +release = "0.0.7" + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx_autodoc_typehints", +] + +autodoc_default_options = { + "members": True, + "undoc-members": False, + "private-members": False, + "show-inheritance": True, + "inherited-members": True, +} + +autodoc_typehints = "description" +napoleon_google_docstring = True +autosummary_generate = True +autosummary_imported_members = False + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] +html_title = f"{project} {release} documentation" + +# Explicit root doc (Sphinx defaults to 'index' but be explicit). +root_doc = "index" diff --git a/docs/source/images/example.gif b/docs/images/example.gif similarity index 100% rename from docs/source/images/example.gif rename to docs/images/example.gif diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..24fe20b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,24 @@ +Welcome to cmdcraft documentation! +================================== + +``cmdcraft`` is a library that aims to build fast and stable +interactive devtools. It uses native Python metadata from objects to build prompt +commands, so you don't have to manually configure input options. + +Table of Contents +----------------- + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + pages/intro/index + pages/howto/crafting + pages/contributing + pages/changelog + pages/documentation + +Special thanks +============== + +- `Python Prompt Toolkit `_: Awesome prompt utility. \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 747ffb7..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -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/CHANGELOG.rst b/docs/pages/changelog.rst similarity index 96% rename from CHANGELOG.rst rename to docs/pages/changelog.rst index a5b7fe6..c46f76d 100644 --- a/CHANGELOG.rst +++ b/docs/pages/changelog.rst @@ -28,7 +28,7 @@ v0.0.4 - Improve linting Fixed issues: -****** +************* #2: Exception while typing quoted arguments v0.0.3 @@ -40,7 +40,7 @@ v0.0.3 v0.0.2 Fixed issues: -****** +************* #1: Input mishandling options - Input handling diff --git a/CONTRIBUING.rst b/docs/pages/contributing.rst similarity index 80% rename from CONTRIBUING.rst rename to docs/pages/contributing.rst index 79da79f..b8e1cb8 100644 --- a/CONTRIBUING.rst +++ b/docs/pages/contributing.rst @@ -28,4 +28,10 @@ we ask to start the brief message with one of these tags: - `infra`: The commit contains changes to the project infrastructure Also, if the commit is related to a specific tracked issue, please insert its number -preceded by #. \ No newline at end of file +preceded by #. + +Local checks +============ + +Use ``./tools/lint.sh --changed`` to lint only the Python files changed on your branch, +or ``./tools/lint.sh --all`` for a full-repository Ruff check plus formatting validation. diff --git a/docs/pages/documentation.rst b/docs/pages/documentation.rst new file mode 100644 index 0000000..c1c309d --- /dev/null +++ b/docs/pages/documentation.rst @@ -0,0 +1,20 @@ +Documentation +============= + +BasePrompter +------------ + +.. automodule:: cmdcraft.base + :members: + +Prompter +-------- + +.. automodule:: cmdcraft.prompter + :members: + +Command +------- + +.. automodule:: cmdcraft.command + :members: \ No newline at end of file diff --git a/docs/source/pages/howto/crafting.rst b/docs/pages/howto/crafting.rst similarity index 100% rename from docs/source/pages/howto/crafting.rst rename to docs/pages/howto/crafting.rst diff --git a/docs/source/pages/intro/getting_started.rst b/docs/pages/intro/getting_started.rst similarity index 100% rename from docs/source/pages/intro/getting_started.rst rename to docs/pages/intro/getting_started.rst diff --git a/docs/source/pages/intro/index.rst b/docs/pages/intro/index.rst similarity index 100% rename from docs/source/pages/intro/index.rst rename to docs/pages/intro/index.rst diff --git a/docs/source/pages/intro/known_issues.rst b/docs/pages/intro/known_issues.rst similarity index 100% rename from docs/source/pages/intro/known_issues.rst rename to docs/pages/intro/known_issues.rst diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 58af305..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,27 +0,0 @@ -# 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 - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "cmdcraft" -copyright = "2024, A. M. Weinsen Jr" -author = "A. M. Weinsen Jr" -release = "0.0.7" - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = ["sphinx.ext.autodoc"] - -templates_path = ["_templates"] -exclude_patterns = [] - - -# -- 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"] diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 27909f4..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -cmdcraft documentation -========================== - -cmdcraft (or simply ``cmdcraft``) is a library that aims to build fast and stable -interative devtools. It that native Python metadata from objects to build prompt -commands, so you don't have to manually configure input options. - -.. image:: images/example.gif - -Features --------- - -- Asynchronous and parallel tasks using asyncio -- Easy function to command interface -- Out of box functionality -- Intuitive usability - -Table of Contents ------------------ - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - pages/intro/index - pages/howto/crafting - pages/documentation - -Special thanks -============== - -- `Python Prompt Toolkit `_: Awesome prompt utility. \ No newline at end of file diff --git a/docs/source/pages/documentation.rst b/docs/source/pages/documentation.rst deleted file mode 100644 index fbc6b72..0000000 --- a/docs/source/pages/documentation.rst +++ /dev/null @@ -1,14 +0,0 @@ -Documentation -============= - -Prompter ------------ - -.. automodule:: cmdcraft.interpreter - :members: - -Command ------------ - -.. automodule:: cmdcraft.command - :members: \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 99dddb7..abd371b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,13 +35,17 @@ dev = [ "ruff", ] docs = [ - "furo", - "sphinx", + "sphinx>=6.0", + "sphinx-rtd-theme", + "sphinx-autodoc-typehints", + "sphinx-autobuild", ] [project.urls] -Homepage = "https://github.com/weinsen/cmdcraft" -Repository = "https://github.com/weinsen/cmdcraft" +"Homepage" = "https://github.com/weinsen/cmdcraft" +"Repository" = "https://github.com/weinsen/cmdcraft" +"Bug Reports" = "https://github.com/weinsen/cmdcraft/issues" +"Docs" = "https://cmdcraft.readthedocs.io/en/latest/?badge=latest" [tool.setuptools] package-dir = {"" = "src"}