Merge pull request #104 from collective/docs

docs: Add code examples for using tab libraries
collective · Aug 18, 2024 · d7f8004 · d7f8004
2 parents 48f8d7a + 47ccef1
commit d7f8004
Show file tree

Hide file tree

Showing 36 changed files with 475 additions and 87 deletions.
diff --git a/Makefile b/Makefile
@@ -65,8 +65,8 @@ env:
 .coverage: $(TEST) $(SRC)
 	coverage run setup.py test
 
-nix/requirements-python27.nix: .cache nix/requirements-python27.txt
-	nix develop .#python27-pip2nix --command pip2nix generate -r nix/requirements-python27.txt --output=nix/requirements-python27.nix
+nix/requirements-python27-%.nix: .cache nix/requirements-python27-%.txt
+	nix develop .#pip2nix --command pip2nix generate -r nix/requirements-python27-$*.txt --output=nix/requirements-python27-$*.nix
 
 nix/requirements-python27.txt: .cache requirements.txt
 	nix develop .#python27-pip2nix --command pip2nix generate -r requirements.txt --output=nix/requirements-python27.nix
@@ -80,12 +80,18 @@ poetry\ add\ --dev\ %:
 	mv poetry.lock nix/poetry-$(PYTHON)-$(FEATURE).lock
 
 every\ poetry\ add\ --dev\ %:
+	 PYTHON=python39  FEATURE=docutils016 $(MAKE) poetry\ add\ --dev\ $*
+	 PYTHON=python39  FEATURE=docutils017 $(MAKE) poetry\ add\ --dev\ $*
 	 PYTHON=python39  FEATURE=docutils018 $(MAKE) poetry\ add\ --dev\ $*
 	 PYTHON=python39  FEATURE=docutils019 $(MAKE) poetry\ add\ --dev\ $*
 	 PYTHON=python39  FEATURE=docutils020 $(MAKE) poetry\ add\ --dev\ $*
+	 PYTHON=python310 FEATURE=docutils016 $(MAKE) poetry\ add\ --dev\ $*
+	 PYTHON=python310 FEATURE=docutils017 $(MAKE) poetry\ add\ --dev\ $*
 	 PYTHON=python310 FEATURE=docutils018 $(MAKE) poetry\ add\ --dev\ $*
 	 PYTHON=python310 FEATURE=docutils019 $(MAKE) poetry\ add\ --dev\ $*
 	 PYTHON=python310 FEATURE=docutils020 $(MAKE) poetry\ add\ --dev\ $*
+	 PYTHON=python311 FEATURE=docutils016 $(MAKE) poetry\ add\ --dev\ $*
+	 PYTHON=python311 FEATURE=docutils017 $(MAKE) poetry\ add\ --dev\ $*
 	 PYTHON=python311 FEATURE=docutils018 $(MAKE) poetry\ add\ --dev\ $*
 	 PYTHON=python311 FEATURE=docutils019 $(MAKE) poetry\ add\ --dev\ $*
 	 PYTHON=python311 FEATURE=docutils020 $(MAKE) poetry\ add\ --dev\ $*

diff --git a/docs/conf.py b/docs/conf.py
@@ -35,9 +35,11 @@
 ]
 
 try:
+    import sphinx_copybutton
     import sphinx_design
     import sphinx_inline_tabs
     extensions.extend([
+        'sphinx_copybutton',
         'sphinx_design',
         'sphinx_inline_tabs',
     ])
@@ -146,7 +148,9 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'collapse_navigation': False,
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []

diff --git a/docs/usage.rst b/docs/usage.rst
@@ -1,5 +1,5 @@
-Examples of use:
-================
+Examples of use
+===============
 
 
 Examples with inline sources
@@ -342,3 +342,154 @@ Result
 ..  http:example:: curl wget httpie python-requests plone-javascript
     :request: ../tests/fixtures/003.request.txt
     :response: ../tests/fixtures/003.response.txt
+
+
+Examples with tab libraries
+---------------------------
+
+`sphinx-inline-tabs <https://sphinx-inline-tabs.readthedocs.io/en/latest/>`_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Code
+````
+
+..  code-block:: rst
+
+    ..  tab:: http
+
+        ..  http:example-block:: http
+            :request: ../tests/fixtures/001.request.txt
+
+    ..  tab:: curl
+
+        ..  http:example-block:: curl
+            :request: ../tests/fixtures/001.request.txt
+
+    ..  tab:: wget
+
+        ..  http:example-block:: wget
+            :request: ../tests/fixtures/001.request.txt
+
+    ..  tab:: httpie
+
+        ..  http:example-block:: httpie
+            :request: ../tests/fixtures/001.request.txt
+
+    ..  tab:: python-requests
+
+        ..  http:example-block:: wget
+            :request: ../tests/fixtures/001.request.txt
+
+    ..  tab:: response
+
+        ..  http:example-block:: response
+            :response: ../tests/fixtures/001.response.txt
+
+Result
+``````
+
+..  tab:: http
+
+  ..  http:example-block:: http
+      :request: ../tests/fixtures/001.request.txt
+
+..  tab:: curl
+
+  ..  http:example-block:: curl
+      :request: ../tests/fixtures/001.request.txt
+
+..  tab:: wget
+
+  ..  http:example-block:: wget
+      :request: ../tests/fixtures/001.request.txt
+
+..  tab:: httpie
+
+  ..  http:example-block:: httpie
+      :request: ../tests/fixtures/001.request.txt
+
+..  tab:: python-requests
+
+  ..  http:example-block:: wget
+      :request: ../tests/fixtures/001.request.txt
+
+..  tab:: response
+
+  ..  http:example-block:: response
+      :response: ../tests/fixtures/001.response.txt
+
+
+`sphinx-design <https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html>`_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Code
+````
+
+..  code-block:: rst
+
+    ..  tab-set::
+
+      ..  tab-item:: http
+
+          ..  http:example-block:: http
+              :request: ../tests/fixtures/001.request.txt
+
+      ..  tab-item:: curl
+
+          ..  http:example-block:: curl
+              :request: ../tests/fixtures/001.request.txt
+
+      ..  tab-item:: wget
+
+          ..  http:example-block:: wget
+              :request: ../tests/fixtures/001.request.txt
+
+      ..  tab-item:: httpie
+
+          ..  http:example-block:: httpie
+              :request: ../tests/fixtures/001.request.txt
+
+      ..  tab-item:: python-requests
+
+          ..  http:example-block:: wget
+              :request: ../tests/fixtures/001.request.txt
+
+      ..  tab-item:: response
+
+          ..  http:example-block:: response
+              :response: ../tests/fixtures/001.response.txt
+
+Result
+``````
+
+..  tab-set::
+
+  ..  tab-item:: http
+
+      ..  http:example-block:: http
+          :request: ../tests/fixtures/001.request.txt
+
+  ..  tab-item:: curl
+
+      ..  http:example-block:: curl
+          :request: ../tests/fixtures/001.request.txt
+
+  ..  tab-item:: wget
+
+      ..  http:example-block:: wget
+          :request: ../tests/fixtures/001.request.txt
+
+  ..  tab-item:: httpie
+
+      ..  http:example-block:: httpie
+          :request: ../tests/fixtures/001.request.txt
+
+  ..  tab-item:: python-requests
+
+      ..  http:example-block:: wget
+          :request: ../tests/fixtures/001.request.txt
+
+  ..  tab-item:: response
+
+      ..  http:example-block:: response
+          :response: ../tests/fixtures/001.response.txt
diff --git a/nix/poetry-python310-docutils016.lock b/nix/poetry-python310-docutils016.lock
@@ -786,6 +786,24 @@ docs = ["sphinxcontrib-websupport"]
 lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-bugbear", "flake8-comprehensions", "flake8-simplify", "isort", "mypy (>=0.981)", "sphinx-lint", "types-requests", "types-typed-ast"]
 test = ["cython", "html5lib", "pytest (>=4.6)", "typed_ast"]
 
+[[package]]
+name = "sphinx-copybutton"
+version = "0.5.2"
+description = "Add a copy button to each of your code cells."
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd"},
+    {file = "sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e"},
+]
+
+[package.dependencies]
+sphinx = ">=1.8"
+
+[package.extras]
+code-style = ["pre-commit (==2.12.1)"]
+rtd = ["ipython", "myst-nb", "sphinx", "sphinx-book-theme", "sphinx-examples"]
+
 [[package]]
 name = "sphinx-rtd-theme"
 version = "2.0.0"
@@ -1070,4 +1088,4 @@ test = ["pytest (>=6.0.0)", "setuptools (>=65)"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.10"
-content-hash = "d2fb539277ef055c086e91d7e2982b94fbc7117e6447530d4e9da8d0d21defbc"
+content-hash = "3732d0acef966b53539e8b71f7ee75a9bbc696186c2f98329ab28d999a6c6682"
diff --git a/nix/poetry-python310-docutils016.toml b/nix/poetry-python310-docutils016.toml
@@ -44,6 +44,7 @@ sphinx-testing = "^1.0.1"
 flake8 = "^7.1.1"
 sphinx-rtd-theme = "^2.0.0"
 coveralls = "3.3.1"
+sphinx-copybutton = "^0.5.2"
 
 [build-system]
 requires = ["poetry-core"]

diff --git a/nix/poetry-python310-docutils017.lock b/nix/poetry-python310-docutils017.lock
@@ -786,6 +786,24 @@ docs = ["sphinxcontrib-websupport"]
 lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-bugbear", "flake8-comprehensions", "flake8-simplify", "isort", "mypy (>=0.981)", "sphinx-lint", "types-requests", "types-typed-ast"]
 test = ["cython", "html5lib", "pytest (>=4.6)", "typed_ast"]
 
+[[package]]
+name = "sphinx-copybutton"
+version = "0.5.2"
+description = "Add a copy button to each of your code cells."
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd"},
+    {file = "sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e"},
+]
+
+[package.dependencies]
+sphinx = ">=1.8"
+
+[package.extras]
+code-style = ["pre-commit (==2.12.1)"]
+rtd = ["ipython", "myst-nb", "sphinx", "sphinx-book-theme", "sphinx-examples"]
+
 [[package]]
 name = "sphinx-rtd-theme"
 version = "2.0.0"
@@ -1070,4 +1088,4 @@ test = ["pytest (>=6.0.0)", "setuptools (>=65)"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.10"
-content-hash = "d1680bd81bc58b08ff6298fd6dd8c8a3c7f07a9661a813ed2f8c0855349cde1f"
+content-hash = "1a6d507724e4834a8987e906e195ce9885e375000e44f08946320462f8d956ff"
diff --git a/nix/poetry-python310-docutils017.toml b/nix/poetry-python310-docutils017.toml
@@ -44,6 +44,7 @@ sphinx-testing = "^1.0.1"
 flake8 = "^7.1.1"
 sphinx-rtd-theme = "^2.0.0"
 coveralls = "3.3.1"
+sphinx-copybutton = "^0.5.2"
 
 [build-system]
 requires = ["poetry-core"]

diff --git a/nix/poetry-python310-docutils018.lock b/nix/poetry-python310-docutils018.lock
@@ -787,6 +787,24 @@ docs = ["sphinxcontrib-websupport"]
 lint = ["flake8 (>=3.5.0)", "importlib_metadata", "mypy (==1.9.0)", "pytest (>=6.0)", "ruff (==0.3.7)", "sphinx-lint", "tomli", "types-docutils", "types-requests"]
 test = ["cython (>=3.0)", "defusedxml (>=0.7.1)", "pytest (>=6.0)", "setuptools (>=67.0)"]
 
+[[package]]
+name = "sphinx-copybutton"
+version = "0.5.2"
+description = "Add a copy button to each of your code cells."
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd"},
+    {file = "sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e"},
+]
+
+[package.dependencies]
+sphinx = ">=1.8"
+
+[package.extras]
+code-style = ["pre-commit (==2.12.1)"]
+rtd = ["ipython", "myst-nb", "sphinx", "sphinx-book-theme", "sphinx-examples"]
+
 [[package]]
 name = "sphinx-design"
 version = "0.6.1"
@@ -1114,4 +1132,4 @@ test = ["pytest (>=6.0.0)", "setuptools (>=65)"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.10"
-content-hash = "66720a593de2b9c6dd1a08410528c3407d690ad9f8b1110f1c90fe4dcefae718"
+content-hash = "622bd65fd4b334ffb63731c2403d8d674a844607ceccea09ea55086552be5b59"
diff --git a/nix/poetry-python310-docutils018.toml b/nix/poetry-python310-docutils018.toml
@@ -46,6 +46,7 @@ sphinx-rtd-theme = "^2.0.0"
 coveralls = "3.3.1"
 sphinx-design = "^0.6.1"
 sphinx-inline-tabs = "^2023.4.21"
+sphinx-copybutton = "^0.5.2"
 
 [build-system]
 requires = ["poetry-core"]

diff --git a/nix/poetry-python310-docutils019.lock b/nix/poetry-python310-docutils019.lock
@@ -787,6 +787,24 @@ docs = ["sphinxcontrib-websupport"]
 lint = ["flake8 (>=3.5.0)", "importlib_metadata", "mypy (==1.9.0)", "pytest (>=6.0)", "ruff (==0.3.7)", "sphinx-lint", "tomli", "types-docutils", "types-requests"]
 test = ["cython (>=3.0)", "defusedxml (>=0.7.1)", "pytest (>=6.0)", "setuptools (>=67.0)"]
 
+[[package]]
+name = "sphinx-copybutton"
+version = "0.5.2"
+description = "Add a copy button to each of your code cells."
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd"},
+    {file = "sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e"},
+]
+
+[package.dependencies]
+sphinx = ">=1.8"
+
+[package.extras]
+code-style = ["pre-commit (==2.12.1)"]
+rtd = ["ipython", "myst-nb", "sphinx", "sphinx-book-theme", "sphinx-examples"]
+
 [[package]]
 name = "sphinx-design"
 version = "0.6.1"
@@ -1114,4 +1132,4 @@ test = ["pytest (>=6.0.0)", "setuptools (>=65)"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.10"
-content-hash = "570150009d881bacf6cb4c595de2d36cb7b0223cf8a6e44aecb2f663e467536c"
+content-hash = "050bc7caf6af68e4f80b9e289d0264fd54eed1eb52bdfe26648595fd65d6762c"
diff --git a/nix/poetry-python310-docutils019.toml b/nix/poetry-python310-docutils019.toml
@@ -46,6 +46,7 @@ sphinx-rtd-theme = "^2.0.0"
 coveralls = "3.3.1"
 sphinx-design = "^0.6.1"
 sphinx-inline-tabs = "^2023.4.21"
+sphinx-copybutton = "^0.5.2"
 
 [build-system]
 requires = ["poetry-core"]