diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..dbd09e1 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,58 @@ +name: Deploy Documentation + +on: + push: + branches: [master] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.x' + + - name: Install uv + run: python -m pip install --upgrade uv + + - name: Install dependencies + run: | + uv pip install --system -e . + uv pip install --system -r docs/requirements.txt + + - name: Generate API documentation + run: sphinx-apidoc -f -o docs consul --separate + + - name: Build Sphinx documentation + run: sphinx-build -b html docs docs/_build/html + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/_build/html + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + if: github.ref == 'refs/heads/master' + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 0517523..fb17130 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,10 @@ __pycache__ # sphinx build folder _build +# sphinx auto-generated API docs (generated by sphinx-apidoc) +docs/consul*.rst +docs/modules.rst + *.py[co] # Packages @@ -48,3 +52,4 @@ pip-log.txt # IntelliJ project files *.iml .idea/ +logs/ diff --git a/README.md b/README.md index 77eb2fd..8051078 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# py-consul [![PyPi version](https://img.shields.io/pypi/v/py-consul.svg)](https://pypi.python.org/pypi/py-consul/) [![Python version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) ![Status](https://img.shields.io/badge/status-maintained-green.svg) +# py-consul [![PyPi version](https://img.shields.io/pypi/v/py-consul.svg)](https://pypi.python.org/pypi/py-consul/) [![Python version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) ![Status](https://img.shields.io/badge/status-maintained-green.svg) [![Documentation](https://img.shields.io/badge/docs-github%20pages-blue)](https://criteo.github.io/py-consul/) Status ----------- diff --git a/consul/api/agent.py b/consul/api/agent.py index ba47922..809d065 100644 --- a/consul/api/agent.py +++ b/consul/api/agent.py @@ -161,7 +161,7 @@ def register( """ Add a new service to the local agent. There is more documentation on services - `here `_. + `here `_. *name* is the name of the service. @@ -205,7 +205,7 @@ def register( This option is only for >=v0.6.0 version on both agent and servers. for more information - https://www.consul.io/docs/agent/services.html + https://developer.hashicorp.com/consul/docs/fundamentals/service """ if extra_checks is None: @@ -306,7 +306,7 @@ def register( """ Register a new check with the local agent. More documentation on checks can be found `here - `_. + `_. *name* is the name of the check. @@ -411,7 +411,7 @@ def authorize(self, target, client_cert_uri, client_cert_serial, token: str | No Tests whether a connection attempt is authorized between two services. More information is available - `here `_. + `here `_. *target* is the name of the service that is being requested. diff --git a/consul/api/catalog.py b/consul/api/catalog.py index 7053af0..0009a16 100644 --- a/consul/api/catalog.py +++ b/consul/api/catalog.py @@ -64,7 +64,7 @@ def register(self, node, address, service=None, check=None, dc=None, token: str This manipulates the health check entry, but does not setup a script or TTL to actually update the status. The full documentation - is `here `_. + is `here `_. Returns *True* on success. """ diff --git a/consul/api/event.py b/consul/api/event.py index c6feaaf..4c8f05a 100644 --- a/consul/api/event.py +++ b/consul/api/event.py @@ -67,7 +67,7 @@ def list(self, name: str | None = None, index=None, wait=None): *index* is the current event Consul index, suitable for making subsequent calls to wait for changes since this query was last run. - Check https://consul.io/docs/agent/http/event.html#event_list for + Check https://developer.hashicorp.com/consul/api-docs/event for more infos about indexes on events. *wait* the maximum duration to wait (e.g. '10s') to retrieve diff --git a/consul/api/query.py b/consul/api/query.py index d158bcf..fb32e82 100644 --- a/consul/api/query.py +++ b/consul/api/query.py @@ -119,7 +119,7 @@ def create( enter an empty string. For more information about query - https://www.consul.io/docs/agent/http/query.html + https://developer.hashicorp.com/consul/api-docs/query """ path = "/v1/query" params = None if dc is None else [("dc", dc)] diff --git a/consul/api/session.py b/consul/api/session.py index e5e2049..92ad4a7 100644 --- a/consul/api/session.py +++ b/consul/api/session.py @@ -22,7 +22,7 @@ def create( ): """ Creates a new session. There is more documentation for sessions - `here `_. + `here `_. *name* is an optional human readable name for the session. diff --git a/docs/Makefile b/docs/Makefile index c370b08..41c270b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,177 +1,20 @@ -# Makefile for Sphinx documentation +# Minimal makefile for Sphinx documentation # -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = +# 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 -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - +# Put it first so that "make" without argument is like "make help". help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/python-consul.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/python-consul.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/python-consul" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/python-consul" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." +.PHONY: help Makefile -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." +# 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) \ No newline at end of file diff --git a/docs/__init__.py b/docs/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/docs/_static/alabaster.css b/docs/_static/alabaster.css deleted file mode 100644 index e977787..0000000 --- a/docs/_static/alabaster.css +++ /dev/null @@ -1,574 +0,0 @@ - - - - - - - - - - - - - - - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro'; - font-size: 17px; - background-color: white; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - width: 940px; - margin: 30px auto 0 auto; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 220px; -} - -div.sphinxsidebar { - width: 220px; -} - -hr { - border: 1px solid #B1B4B6; -} - -div.body { - background-color: #ffffff; - color: #3E4349; - padding: 0 30px 0 30px; -} - -div.footer { - width: 940px; - margin: 20px auto 30px auto; - font-size: 14px; - color: #888; - text-align: right; -} - -div.footer a { - color: #888; -} - -div.related { - display: none; -} - -div.sphinxsidebar a { - color: #444; - text-decoration: none; - border-bottom: 1px dotted #999; -} - -div.sphinxsidebar a:hover { - border-bottom: 1px solid #999; -} - -div.sphinxsidebar { - font-size: 14px; - line-height: 1.5; -} - -div.sphinxsidebarwrapper { - padding: 18px 10px; -} - -div.sphinxsidebarwrapper p.logo { - padding: 0; - margin-top: -10px; - margin-bottom: 10px; -} - -div.sphinxsidebarwrapper h1.logo { - margin-top: -10px; - text-align: center; - margin-bottom: 5px; - text-align: left; -} - -div.sphinxsidebarwrapper h1.logo-name { - margin-top: 0px; -} - -div.sphinxsidebarwrapper p.blurb { - margin-top: 0; -} - -div.sphinxsidebar h3, -div.sphinxsidebar h4 { - font-family: 'Garamond', 'Georgia', serif; - color: #444; - font-size: 24px; - font-weight: normal; - margin: 0 0 5px 0; - padding: 0; -} - -div.sphinxsidebar h4 { - font-size: 20px; -} - -div.sphinxsidebar h3 a { - color: #444; -} - -div.sphinxsidebar p.logo a, -div.sphinxsidebar h3 a, -div.sphinxsidebar p.logo a:hover, -div.sphinxsidebar h3 a:hover { - border: none; -} - -div.sphinxsidebar p { - color: #555; - margin: 10px 0; -} - -div.sphinxsidebar ul { - margin: 10px 0; - padding: 0; - color: #000; -} - -div.sphinxsidebar ul li.toctree-l1 > a { - font-size: 120%; -} - -div.sphinxsidebar ul li.toctree-l2 > a { - font-size: 110%; -} - -div.sphinxsidebar input { - border: 1px solid #CCC; - font-family: 'Georgia', serif; - font-size: 1em; -} - -div.sphinxsidebar hr { - border: none; - height: 1px; - color: #999; - background: #999; - - text-align: left; - margin-left: 0; - width: 50%; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #004B6B; - text-decoration: underline; -} - -a:hover { - color: #6D4100; - text-decoration: underline; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - margin: 30px 0px 10px 0px; - padding: 0; -} - -div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } -div.body h2 { font-size: 180%; } -div.body h3 { font-size: 150%; } -div.body h4 { font-size: 130%; } -div.body h5 { font-size: 100%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #DDD; - padding: 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - color: #444; - background: #EAEAEA; -} - -div.body p, div.body dd, div.body li { - line-height: 1.4em; -} - -div.admonition { - margin: 20px 0px; - padding: 10px 30px; -} - -div.admonition tt.xref, div.admonition a tt { - border-bottom: 1px solid #fafafa; -} - -dd div.admonition { - margin-left: -60px; - padding-left: 60px; -} - -div.admonition p.admonition-title { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - font-size: 24px; - margin: 0 0 10px 0; - padding: 0; - line-height: 1; -} - -div.admonition p.last { - margin-bottom: 0; -} - -div.highlight { - background-color: white; -} - -dt:target, .highlight { - background: #FAF3E8; -} - -div.note { - background-color: #EEE; - border: 1px solid #CCC; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre, tt { - font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.9em; -} - -img.screenshot { -} - -tt.descname, tt.descclassname { - font-size: 0.95em; -} - -tt.descname { - padding-right: 0.08em; -} - -img.screenshot { - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils { - border: 1px solid #888; - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils td, table.docutils th { - border: 1px solid #888; - padding: 0.25em 0.7em; -} - -table.field-list, table.footnote { - border: none; - -moz-box-shadow: none; - -webkit-box-shadow: none; - box-shadow: none; -} - -table.footnote { - margin: 15px 0; - width: 100%; - border: 1px solid #EEE; - background: #FDFDFD; - font-size: 0.9em; -} - -table.footnote + table.footnote { - margin-top: -15px; - border-top: none; -} - -table.field-list th { - padding: 0 0.8em 0 0; -} - -table.field-list td { - padding: 0; -} - -table.footnote td.label { - width: 0px; - padding: 0.3em 0 0.3em 0.5em; -} - -table.footnote td { - padding: 0.3em 0.5em; -} - -dl { - margin: 0; - padding: 0; -} - -dl dd { - margin-left: 30px; -} - -blockquote { - margin: 0 0 0 30px; - padding: 0; -} - -ul, ol { - margin: 10px 0 10px 30px; - padding: 0; -} - -pre { - background: #EEE; - padding: 7px 30px; - margin: 15px 0px; - line-height: 1.3em; -} - -dl pre, blockquote pre, li pre { - margin-left: -60px; - padding-left: 60px; -} - -dl dl pre { - margin-left: -90px; - padding-left: 90px; -} - -tt { - background-color: #ecf0f3; - color: #222; - /* padding: 1px 2px; */ -} - -tt.xref, a tt { - background-color: #FBFBFB; - border-bottom: 1px solid white; -} - -a.reference { - text-decoration: none; - border-bottom: 1px dotted #004B6B; -} - -a.reference:hover { - border-bottom: 1px solid #6D4100; -} - -a.footnote-reference { - text-decoration: none; - font-size: 0.7em; - vertical-align: top; - border-bottom: 1px dotted #004B6B; -} - -a.footnote-reference:hover { - border-bottom: 1px solid #6D4100; -} - -a:hover tt { - background: #EEE; -} - - -@media screen and (max-width: 870px) { - - div.sphinxsidebar { - display: none; - } - - div.document { - width: 100%; - - } - - div.documentwrapper { - margin-left: 0; - margin-top: 0; - margin-right: 0; - margin-bottom: 0; - } - - div.bodywrapper { - margin-top: 0; - margin-right: 0; - margin-bottom: 0; - margin-left: 0; - } - - ul { - margin-left: 0; - } - - .document { - width: auto; - } - - .footer { - width: auto; - } - - .bodywrapper { - margin: 0; - } - - .footer { - width: auto; - } - - .github { - display: none; - } - - - -} - - - -@media screen and (max-width: 875px) { - - body { - margin: 0; - padding: 20px 30px; - } - - div.documentwrapper { - float: none; - background: white; - } - - div.sphinxsidebar { - display: block; - float: none; - width: 102.5%; - margin: 50px -30px -20px -30px; - padding: 10px 20px; - background: #333; - color: #FFF; - } - - div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p, - div.sphinxsidebar h3 a { - color: white; - } - - div.sphinxsidebar a { - color: #AAA; - } - - div.sphinxsidebar p.logo { - display: none; - } - - div.document { - width: 100%; - margin: 0; - } - - div.related { - display: block; - margin: 0; - padding: 10px 0 20px 0; - } - - div.related ul, - div.related ul li { - margin: 0; - padding: 0; - } - - div.footer { - display: none; - } - - div.bodywrapper { - margin: 0; - } - - div.body { - min-height: 0; - padding: 0; - } - - .rtd_doc_footer { - display: none; - } - - .document { - width: auto; - } - - .footer { - width: auto; - } - - .footer { - width: auto; - } - - .github { - display: none; - } -} - - -/* misc. */ - -.revsys-inline { - display: none!important; -} - -/* Make nested-list/multi-paragraph items look better in Releases changelog - * pages. Without this, docutils' magical list fuckery causes inconsistent - * formatting between different release sub-lists. - */ -div#changelog > div.section > ul > li > p:only-child { - margin-bottom: 0; -} diff --git a/docs/_static/logo.png b/docs/_static/logo.png deleted file mode 100644 index b2bc9aa..0000000 Binary files a/docs/_static/logo.png and /dev/null differ diff --git a/docs/_templates/navigation.html b/docs/_templates/navigation.html deleted file mode 100644 index 63109d9..0000000 --- a/docs/_templates/navigation.html +++ /dev/null @@ -1,4 +0,0 @@ -
-

Navigation

-{{ toc }} -
diff --git a/docs/conf.py b/docs/conf.py index 2031fd2..815077e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,285 +1,69 @@ -# -# python-consul documentation build configuration file, created by -# sphinx-quickstart on Sun Sep 28 05:56:44 2014. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +# 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 os -import sys +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. +project = 'py-consul' +copyright = '2025, Criteo' +author = 'Criteo' -sys.path.insert(0, os.path.abspath("..")) - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ "sphinx.ext.autodoc", - # 'sphinx.ext.doctest', - # 'sphinx.ext.coverage', - # 'sphinx.ext.viewcode', + "sphinx.ext.napoleon", + "sphinx.ext.githubpages", + "sphinx.ext.intersphinx", # Link to other project docs (e.g., Python stdlib) + "sphinx.ext.viewcode", # Add links to source code + "myst_parser", ] -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix of source filenames. -source_suffix = ".rst" - -# The encoding of source files. -# source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = "index" - -# General information about the project. -project = "python-consul" -copyright = "2014, Andy Gayton" - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = "0.1" -# The full version, including alpha/beta/rc tags. -release = "0.1" - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# today = '' -# Else, today_fmt is used as the format for a strftime call. -# today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ["_build"] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -# keep_warnings = False +# Autodoc settings +autoclass_content = 'both' +autodoc_member_order = 'bysource' # Keep source order instead of alphabetical +autodoc_typehints = 'description' # Show type hints in description, not signature +# Intersphinx - link to external docs +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), +} +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] -# -- Options for HTML output ---------------------------------------------- +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -import alabaster - -html_theme_path = [alabaster.get_path()] -extensions.append("alabaster") -html_theme = "alabaster" -html_sidebars = { - "**": [ - "about.html", - "navigation.html", - # 'searchbox.html', 'donate.html', - ] -} +html_theme = 'furo' +# Furo theme options html_theme_options = { - "github_user": "cablehead", - "github_repo": "python-consul", - "logo": "logo.png", - "logo_name": True, + "source_repository": "https://github.com/criteo/py-consul/", + "source_branch": "master", + "source_directory": "docs/", + "navigation_with_keys": True, + "top_of_page_button": "edit", } -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -# html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -# html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# html_additional_pages = {} - -# If false, no module index is generated. -# html_domain_indices = True - -# If false, no index is generated. -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = "python-consuldoc" - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - #'preamble': '', +# Show "Edit on GitHub" links +html_context = { + "display_github": True, + "github_user": "criteo", + "github_repo": "py-consul", + "github_version": "master", + "conf_py_path": "/docs/", } -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ("index", "python-consul.tex", "python-consul Documentation", "Andy Gayton", "manual"), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# latex_use_parts = False - -# If true, show page references after internal links. -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# latex_appendices = [] - -# If false, no module index is generated. -# latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [("index", "python-consul", "python-consul Documentation", ["Andy Gayton"], 1)] - -# If true, show URL addresses after external links. -# man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - "index", - "python-consul", - "python-consul Documentation", - "Andy Gayton", - "python-consul", - "One line description of project.", - "Miscellaneous", - ), -] - -# Documents to append as an appendix to all manuals. -# texinfo_appendices = [] - -# If false, no module index is generated. -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -# texinfo_no_detailmenu = False - -autodoc_member_order = "bysource" -autoclass_content = "both" - - -def clean_check_signature(app, what, name, obj, options, signature, return_annotation): - if name.startswith("consul.Check") and signature: - signature = "(" + signature[len("(klass, ") :] - return (signature, return_annotation) - - -def setup(app): - app.connect("autodoc-process-signature", clean_check_signature) +# Show deeper TOC levels in sidebar for better subpage navigation +html_sidebars = { + "**": [ + "sidebar/scroll-start.html", + "sidebar/brand.html", + "sidebar/search.html", + "sidebar/navigation.html", + "sidebar/ethical-ads.html", + "sidebar/scroll-end.html", + ] +} \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 2b7390e..67b31ca 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,267 +1,11 @@ -.. include:: ../README.rst +.. include:: ../README.md + :parser: myst_parser.sphinx_ -Clients -------- +API Reference +============= -This library is designed to be easily adapted for a number of clients. -Particularly asynchronous clients. The following clients are currently -supported. +.. toctree:: + :maxdepth: 5 + :caption: Contents: -Standard -~~~~~~~~ - -This is a standard blocking python client. It isn't particularly useful for -creating server components - but it does serve as a base. It makes use of the -`requests`_ library for http requests. - -.. code:: python - - >>> import consul - - >>> c = consul.Consul() - - >>> c.kv.put('foo', 'bar') - True - - >>> index, data = c.kv.get('foo') - >>> data['Value'] - 'bar' - - # this will block until there's an update or a timeout - >>> index, data = c.kv.get('foo', index=index) - -Vanilla -~~~~~~~ - -An asynchronous `Vanilla`_ plugin based on this library is available at: -https://github.com/cablehead/vanilla.consul - -gevent -~~~~~~ - -The terribly awful thing about `gevent`_ is that anything that uses the socket -library from the python standard lib, including the `requests`_ library can be -made non-blocking via monkey patching. This means the standard python-consul -client will just work asynchronously with `gevent`_. - -asyncio -~~~~~~~ - -There is a `asyncio`_ (using aiohttp_) client which works with `Python3.4` and -makes use of `asyncio.coroutine`_. The API for this client is identical to -the standard python-consul client except that you need to ``yield from`` the -result of each API call. This client is available in *consul.aio*. - -.. code:: python - - import asyncio - import consul.aio - - - loop = asyncio.get_running_loop() - - @asyncio.coroutine - def go(): - - # always better to pass ``loop`` explicitly, but this - # is not mandatory, you can relay on global event loop - c = consul.aio.Consul(port=consul_port, loop=loop) - - # set value, same as default api but with ``yield from`` - response = yield from c.kv.put(b'foo', b'bar') - assert response is True - - # get value - index, data = yield from c.kv.get(b'foo') - assert data['Value'] == b'bar' - - # delete value - response = yield from c.kv.delete(b'foo2') - assert response is True - - loop.run_until_complete(go()) - - -Tools ------ - -Handy tools built on python-consul. - -`ianitor`_ -~~~~~~~~~~ - -`ianitor`_ is a doorkeeper for your services discovered using consul. It can -automatically register new services through consul API and manage TTL health -checks. - -Example Uses ------------- - -ACLs -~~~~ - -.. code:: python - - import consul - - # master_token is a *management* token, for example the *acl_master_token* - # you started the Consul server with - master = consul.Consul(token=master_token) - - master.kv.put('foo', 'bar') - master.kv.put('private/foo', 'bar') - - rules = """ - key "" { - policy = "read" - } - key "private/" { - policy = "deny" - } - """ - token = master.acl.create(rules=rules) - - client = consul.Consul(token=token) - - client.kv.get('foo') # OK - client.kv.put('foo', 'bar2') # raises ACLPermissionDenied - - client.kv.get('private/foo') # returns None, as though the key doesn't - # exist - slightly unintuitive - client.kv.put('private/foo', 'bar2') # raises ACLPermissionDenied - -API Documentation ------------------ - -Check -~~~~~ - -.. autoclass:: consul.Check - -Check.docker -++++++++++++ - -.. automethod:: consul.Check.docker - -Check.script -++++++++++++ - -.. automethod:: consul.Check.script - -Check.http -++++++++++ - -.. automethod:: consul.Check.http - -Check.tcp -+++++++++ - -.. automethod:: consul.Check.tcp - -Check.ttl -+++++++++ - -.. automethod:: consul.Check.ttl - - -Consul -~~~~~~ - -.. autoclass:: consul.Consul - -Consul.acl -++++++++++ - -.. autoclass:: consul.base::Consul.ACL() - :members: - :undoc-members: - -Consul.agent -++++++++++++ - -.. autoclass:: consul.base::Consul.Agent() - :members: - :exclude-members: Service - -.. autoclass:: consul.base::Consul.Agent.Service() - :members: - -.. autoclass:: consul.base::Consul.Agent.Check() - :members: - -Consul.catalog -++++++++++++++ - -.. autoclass:: consul.base::Consul.Catalog() - :members: - :undoc-members: - -Consul.event -++++++++++++ - -.. autoclass:: consul.base::Consul.Event() - :members: - :undoc-members: - -Consul.coordinate -+++++++++++++++++ - -.. autoclass:: consul.base::Consul.Coordinate() - :members: - :undoc-members: - -Consul.health -+++++++++++++ - -.. autoclass:: consul.base::Consul.Health() - :members: - :undoc-members: - :exclude-members: Check - -Consul.kv -+++++++++ - -.. autoclass:: consul.base::Consul.KV() - :members: - :undoc-members: - -Consul.query -++++++++++++ - -.. autoclass:: consul.base::Consul.Query() - :members: - :undoc-members: - -Consul.session -++++++++++++++ - -.. autoclass:: consul.base::Consul.Session() - :members: - :undoc-members: - -Consul.status -+++++++++++++ - -.. autoclass:: consul.base::Consul.Status() - :members: - :undoc-members: - -Consul.txn -++++++++++ - -.. autoclass:: consul.base::Consul.Txn() - :members: - :undoc-members: - - -.. _ACL Token: http://www.consul.io/docs/internals/acl.html -.. _HCL: https://github.com/hashicorp/hcl/ -.. _requests: http://python-requests.org -.. _Vanilla: https://github.com/cablehead/vanilla -.. _gevent: http://www.gevent.org -.. _asyncio.coroutine: https://docs.python.org/3/library/asyncio-task.html#coroutines -.. _aiohttp: https://github.com/KeepSafe/aiohttp -.. _asyncio: https://docs.python.org/3/library/asyncio.html -.. _thread pool: https://docs.python.org/2/library/threading.html - -.. _ianitor: https://github.com/ClearcodeHQ/ianitor + modules diff --git a/docs/requirements.txt b/docs/requirements.txt index c6f6446..2d205db 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1,3 @@ -alabaster +furo +myst-parser +sphinx