diff --git a/docs/Makefile b/docs/Makefile index e85440e47..278a71c7f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,177 +1,19 @@ -# Makefile for Sphinx documentation -# +# 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/Falcon.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Falcon.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/Falcon" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Falcon" - @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) diff --git a/docs/_static/custom-icons.js b/docs/_static/custom-icons.js new file mode 100644 index 000000000..e1fe2f115 --- /dev/null +++ b/docs/_static/custom-icons.js @@ -0,0 +1,34 @@ +/******************************************************************************* + * Set a custom icon for pypi as it's not available in the fa built-in brands + */ +FontAwesome.library.add( + (faListOldStyle = { + prefix: "fa-custom", + iconName: "pypi", + icon: [ + 17.313, // viewBox width + 19.807, // viewBox height + [], // ligature + "e001", // unicode codepoint - private use area + "m10.383 0.2-3.239 1.1769 3.1883 1.1614 3.239-1.1798zm-3.4152 1.2411-3.2362 1.1769 3.1855 1.1614 3.2369-1.1769zm6.7177 0.00281-3.2947 1.2009v3.8254l3.2947-1.1988zm-3.4145 1.2439-3.2926 1.1981v3.8254l0.17548-0.064132 3.1171-1.1347zm-6.6564 0.018325v3.8247l3.244 1.1805v-3.8254zm10.191 0.20931v2.3137l3.1777-1.1558zm3.2947 1.2425-3.2947 1.1988v3.8254l3.2947-1.1988zm-8.7058 0.45739c0.00929-1.931e-4 0.018327-2.977e-4 0.027485 0 0.25633 0.00851 0.4263 0.20713 0.42638 0.49826 1.953e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36226 0.13215-0.65608-0.073306-0.65613-0.4588-6.28e-5 -0.38556 0.2938-0.80504 0.65613-0.93662 0.068422-0.024919 0.13655-0.038114 0.20156-0.039466zm5.2913 0.78369-3.2947 1.1988v3.8247l3.2947-1.1981zm-10.132 1.239-3.2362 1.1769 3.1883 1.1614 3.2362-1.1769zm6.7177 0.00213-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2439-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.016195v3.8275l3.244 1.1805v-3.8254zm16.9 0.21143-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2432-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.019027v3.8247l3.244 1.1805v-3.8254zm13.485 1.4497-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm2.4018 0.38127c0.0093-1.83e-4 0.01833-3.16e-4 0.02749 0 0.25633 0.0085 0.4263 0.20713 0.42638 0.49826 1.97e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36188 0.1316-0.65525-0.07375-0.65542-0.4588-1.95e-4 -0.38532 0.29328-0.80469 0.65542-0.93662 0.06842-0.02494 0.13655-0.03819 0.20156-0.03947zm-5.8142 0.86403-3.244 1.1805v1.4201l3.244 1.1805z", // svg path (https://simpleicons.org/icons/pypi.svg) + ], + }), +); + +/******************************************************************************* + * Set a custom icon for Falcon as it's not available in the fa built-in brands. + * NOTE(vytas): But one day we'll be there ("big as Django"). + */ +FontAwesome.library.add( + (faListOldStyle = { + prefix: "fa-custom", + iconName: "falcon", + icon: [ + 16.0, // viewBox width + 16.0, // viewBox height + [], // ligature + "e002", // unicode codepoint - private use area + "M 2.54188 0.40205 C 1.38028 1.60365 0.794478 2.81526 0.794478 4.02187 C 0.794478 4.29723 0.814578 4.53255 0.844578 4.54757 C 0.874678 4.56258 0.894678 4.62768 0.894678 4.68775 C 0.894678 4.82794 1.01478 5.1734 1.17508 5.49883 C 1.38528 5.93441 1.69068 6.23982 2.52188 6.84062 C 3.17268 7.31124 3.53318 7.84195 3.65338 8.51284 L 3.71838 8.87332 L 3.89868 8.79822 C 4.35428 8.60296 4.70468 8.53287 5.75108 8.42272 C 6.42198 8.35263 6.68238 8.2525 6.99278 7.94709 C 7.43336 7.5065 7.22308 7.22112 5.84628 6.40504 C 4.36428 5.52386 3.83358 5.11332 3.25778 4.39737 C 2.79718 3.8216 2.56188 3.34597 2.44668 2.75518 C 2.33658 2.20445 2.48678 1.33329 2.82218 0.55225 C 2.91738 0.321944 2.99748 0.121677 2.99748 0.101651 C 2.99748 -0.00348278 2.83228 0.106713 2.54188 0.40205 Z M 15.8896 0.80759 C 15.8646 0.827621 15.7995 0.927752 15.7544 1.02788 C 15.464 1.64871 14.5028 2.23449 12.9857 2.70511 C 12.8506 2.75018 12.6102 2.82026 12.46 2.87033 C 12.3098 2.9154 12.0144 3.01052 11.8092 3.0706 C 9.26079 3.84663 8.8152 4.24717 7.90398 6.55023 C 7.49344 7.5816 7.27815 7.92706 6.85258 8.20744 C 6.49708 8.44776 6.20668 8.52786 5.40068 8.628 C 4.11898 8.7832 3.62328 8.9334 3.22278 9.28887 C 2.97738 9.49915 2.89728 9.71945 2.89728 10.16 C 2.89728 10.3603 2.87728 10.5355 2.85728 10.5506 C 2.83218 10.5656 2.78718 10.7008 2.75208 10.856 C 2.70208 11.0662 2.70208 11.1714 2.74698 11.3066 C 2.81708 11.5118 3.01238 11.6821 3.18758 11.6821 C 3.31278 11.6821 3.31778 11.647 3.22268 11.4217 C 3.20258 11.3666 3.23268 11.2965 3.31778 11.2064 C 3.42798 11.0963 3.48298 11.0813 3.82348 11.0813 C 4.21398 11.0813 4.34418 11.0412 4.52938 10.871 C 4.63458 10.7759 4.63958 10.7759 4.77978 10.9311 C 5.07518 11.2565 5.84618 11.7171 6.80748 12.1477 C 7.26304 12.353 7.54842 12.5983 7.76371 12.9788 C 7.9089 13.2291 7.92893 13.2992 7.92893 13.6597 C 7.92893 14.2455 7.71865 14.646 7.3081 14.8363 C 7.23801 14.8713 7.13787 14.9164 7.09281 14.9414 C 7.04274 14.9664 6.85748 14.9864 6.67728 14.9864 L 6.35188 14.9864 L 6.24668 15.2218 C 6.18658 15.3569 6.11148 15.5222 6.07148 15.5923 C 6.01638 15.7024 6.01638 15.7374 6.07148 15.8176 C 6.13658 15.9027 6.15658 15.8927 6.39688 15.6473 C 6.64718 15.392 6.80238 15.3169 6.80238 15.4571 C 6.80238 15.4971 6.71228 15.5973 6.60718 15.6824 C 6.36188 15.8776 6.32678 16.0178 6.44198 16.3483 C 6.53708 16.6186 6.66228 16.6987 6.69228 16.5135 C 6.70228 16.4584 6.77738 16.3483 6.85748 16.2682 C 6.93758 16.193 7.00268 16.0979 7.00268 16.0629 C 7.00268 16.0278 7.03775 15.9728 7.0778 15.9377 C 7.18794 15.8476 7.233 16.0078 7.16292 16.2581 C 7.11786 16.4284 7.12286 16.4784 7.18794 16.5485 C 7.23801 16.6036 7.25303 16.6787 7.23301 16.7638 C 7.21303 16.8539 7.22304 16.889 7.26811 16.889 C 7.3382 16.889 7.50342 16.7338 7.50342 16.6687 C 7.50342 16.6487 7.54848 16.5636 7.60856 16.4834 C 7.7137 16.3332 7.7187 16.3032 7.62358 15.7725 C 7.60856 15.6724 7.61357 15.5873 7.63359 15.5873 C 7.73873 15.5873 8.09921 15.8176 8.11924 15.8977 C 8.15428 16.0278 8.30448 15.9527 8.30448 15.8025 C 8.30448 15.6123 8.1693 15.402 8.00408 15.3269 C 7.83886 15.2568 7.80882 15.1467 7.944 15.1066 C 8.25946 15.0065 8.55485 14.8262 8.8202 14.5609 C 9.14063 14.2505 9.1957 14.1854 9.40098 13.885 C 9.68636 13.4694 9.95171 13.2842 10.2571 13.2842 C 10.6777 13.2842 11.9994 13.875 13.0208 14.5208 C 13.4964 14.8212 14.4277 15.4721 14.5829 15.6123 C 14.6129 15.6423 14.7831 15.7675 14.9634 15.8977 C 15.1436 16.0228 15.454 16.2632 15.6543 16.4334 C 15.8546 16.5986 16.0348 16.7388 16.0548 16.7388 C 16.22 16.7388 16.2751 16.3082 16.1299 16.178 C 16.0799 16.138 15.9046 16.0278 15.7394 15.9377 C 15.3739 15.7324 14.668 15.2568 14.3626 15.0015 C 13.6717 14.4357 12.7905 13.3293 12.2047 12.2929 C 12.1496 12.2078 12.0645 12.0526 12.0094 11.9524 C 11.5889 11.2164 10.7878 10.2802 10.5725 10.2802 C 10.4874 10.2802 10.4874 10.2752 10.6226 9.62933 C 10.6626 9.42405 10.7227 9.07359 10.7528 8.8533 C 10.8429 8.24248 10.9731 7.54656 11.0682 7.2011 C 11.3385 6.18474 11.9143 5.47881 12.9607 4.88802 C 14.4277 4.05191 15.0134 3.53622 15.434 2.70011 C 15.6593 2.25451 15.7044 2.14437 15.8395 1.6437 C 15.9096 1.38836 15.9947 0.767537 15.9597 0.767537 C 15.9497 0.767537 15.9196 0.787568 15.8896 0.807587 Z M 7.22808 12.6483 C 7.21807 12.6834 7.20305 12.8086 7.18803 12.9387 C 7.158 13.2892 6.92268 13.7548 6.65228 14.0052 C 6.32688 14.3106 6.12658 14.4057 5.95638 14.3406 C 5.88628 14.3156 5.68608 14.2755 5.51578 14.2605 C 5.26548 14.2305 5.17538 14.2455 5.05518 14.3156 C 4.92498 14.3907 4.89998 14.4407 4.89998 14.5959 C 4.89998 14.8162 4.89488 14.8112 5.08018 14.7111 C 5.16038 14.671 5.25548 14.636 5.29048 14.636 C 5.39568 14.636 5.35558 14.7361 5.22538 14.7962 C 5.08028 14.8613 5.04018 14.9864 5.03018 15.377 C 5.02508 15.6724 5.11528 15.7875 5.19538 15.5772 C 5.22038 15.5122 5.31558 15.422 5.40568 15.372 C 5.50078 15.3219 5.63098 15.1917 5.70108 15.0866 C 5.83118 14.8663 5.90128 14.8312 5.90128 14.9814 C 5.90128 15.3019 6.06658 15.3169 6.20668 15.0065 C 6.29188 14.8363 6.33688 14.7912 6.39698 14.8162 C 6.56218 14.8863 6.75748 14.8963 6.82758 14.8363 C 6.89768 14.7762 6.89268 14.7562 6.79748 14.656 C 6.73748 14.5909 6.69238 14.5309 6.70738 14.5208 C 6.81758 14.4407 7.05787 14.3857 7.3032 14.3857 C 7.74378 14.3857 7.80386 14.3106 7.80386 13.7448 C 7.80386 13.169 7.65366 12.7585 7.40833 12.6534 C 7.28317 12.6033 7.24311 12.5983 7.22809 12.6483 Z M 11.2584 13.7248 C 11.2584 13.7498 11.4437 13.865 11.674 13.9801 C 12.7805 14.5659 13.4614 15.2017 13.7167 15.9077 C 13.8319 16.2131 13.8369 16.3232 13.7367 16.5535 C 13.6116 16.8589 13.5915 16.8539 14.4026 16.8289 C 15.1336 16.8039 15.5642 16.7238 15.5642 16.6086 C 15.5642 16.5535 14.9634 15.9878 14.7431 15.8426 C 14.683 15.8025 14.6279 15.7525 14.6129 15.7375 C 14.5979 15.7224 14.4978 15.6423 14.3876 15.5572 C 14.2775 15.4771 14.1573 15.387 14.1273 15.362 C 14.0922 15.3319 14.0121 15.2718 13.952 15.2268 C 13.8869 15.1767 13.7468 15.0666 13.6366 14.9815 C 13.5265 14.8963 13.3562 14.7812 13.2611 14.7311 C 13.0308 14.606 12.8906 14.5158 12.8606 14.4808 C 12.8255 14.4407 12.1346 14.0652 11.8092 13.91 C 11.659 13.8399 11.4938 13.7598 11.4487 13.7348 C 11.3385 13.6747 11.2584 13.6697 11.2584 13.7248 Z", + ], + }), +); diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 8948ecc90..781a7ff62 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -1,370 +1,26 @@ -body { - font-family: Oxygen, 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro', serif; - font-size: 17.5px; -} - - -.field-name { - /* Fix for https://github.com/bitprophet/alabaster/issues/95 */ - -moz-hyphens: manual; - -ms-hyphens: manual; - -webkit-hyphens: manual; - hyphens: manual; - - width: 110px; /* Prevent "Return type:" from wrapping. */ -} - -a { - text-decoration: none; -} - -h1 a:hover, h2 a:hover, h3 a:hover { - text-decoration: none; - border: none; -} - -div.document { - /* max body width + 60px padding + 220px sidebar */ - max-width: calc(760px + 60px + 220px); -} - -div.footer { - text-align: center; -} - -div.footer a:hover { - border-bottom: none; -} - -dd ul, dd table { - margin-bottom: 1.4em; -} - -table.field-list th, table.field-list td { - padding-top: 1em; -} - -table.field-list tbody tr:first-child th, table.field-list tbody tr:first-child td { - padding-top: 0; -} - -code.docutils.literal { - background-color: rgba(0, 0, 0, 0.06); - padding: 2px 5px 1px 5px; - font-size: 0.88em; -} - -code.xref.docutils.literal { - background-color: transparent; - padding: 0; - font-size: 0.9em; -} - -div.viewcode-block:target { - background: inherit; - background-color: #dadada; - border-radius: 5px; - padding: 5px; -} - -a:hover, div.sphinxsidebar a:hover, a.reference:hover, a.reference.internal:hover code { - color: #f0ad4e; - border-bottom: 1px solid #f0ad4e; -} - -a, div.sphinxsidebar a, a.reference, a code.literal { - color: #c77c11; - border: none; -} - -.highlight pre span { - line-height: 1.5em; -} - -.field-body cite { - font-style: normal; - font-weight: bold; -} - -/* Hide theme's default logo section */ -.logo a { - display: none; -} - -#logo { - position: relative; - left: -13px; -} - -#logo a, -#logo a:hover { - border-bottom: none; -} - -#logo img { - margin: 0; - padding: 0; -} - -#gh-buttons { - margin-top: 2em; -} - -#dev-warning { - background-color: #fdfbe8; - border: 1px solid #ccc; - padding: 10px; - margin-bottom: 1em; - } - -div.warning { - background-color: #fdfbe8; - border: 1px solid #ccc; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6, -div.sphinxsidebar h3 { - font-family: Oxygen, 'goudy old style', serif; - font-weight: bold; - color: #444; -} - -div.sphinxsidebar h3 { - margin: 1.5em 0 0 0; -} - -div.sphinxsidebar h4 { - font-family: Oxygen, Garamond, Georgia, serif; -} - -div.sphinxsidebar ul { - margin-top: 5px; -} - -div.sphinxsidebarwrapper { - padding-top: 0; -} - -div.admonition p.admonition-title { - display: block; - line-height: 1.4em; - font-family: Oxygen, Garamond, Georgia, serif; -} - -div.admonition .last.highlight-default { - display: inline-block; - font-size: smaller; -} - -pre { - /*background-color: #212529;*/ - padding: 1.25em 30px; -} - -.sphinx-tabs div.node, -.sphinx-tabs div.admonition, -.sphinx-tabs div.highlight -{ - margin-left: -8px; - margin-right: -8px; -} - -.highlight pre { - font-size: 14px; -} - - -/* NOTE(kgriffs): Make sure that characters in plain text blocks line up correctly. */ -.highlight-none .highlight pre { - line-height: 1em; - font-family: monospace; -} - -/* Fix drifting to the left in some parameters lists. */ -.field-body li .highlight pre { - float: right; -} - -div input[type="text"] { - padding: 5px; - margin: 0 0 0.5em 0; - font-family: Oxygen, Garamond, Georgia, serif; -} - -div input[type="submit"] { - font-size: 14px; - width: 72px; - height: 27px; - font-weight: 600; - font-family: Oxygen, Garamond, Georgia, serif; - - border: 1px solid #d5d5d5; - border-radius: 3px; - padding: 0 10px; - - color: #333; - background-color: #eee; - background-image: linear-gradient(to bottom,#fcfcfc,#eee); -} - -div input[type="submit"]:hover { - background-color: #ddd; - background-image: linear-gradient(to bottom,#eee,#ddd); - border-color: #ccc; -} - -div input[type="submit"]:active, #searchbox input[type="submit"]:active { - background-color: #dcdcdc; - background-image: none; - border-color: #b5b5b5; - box-shadow: inset 0 2px 4px rgba(0,0,0,.15); -} - -div input[type="submit"]:focus { - outline: none; -} - -input[type=text]:focus { - outline: 1px solid #999; -} - -#sidebarSupportFalcon a:hover, #sidebarSupportFalcon a:focus { - text-decoration: none; - border: none; - outline: none; -} - -dl.field-list > dt { - word-break: normal; - padding-left: 0; - hyphens: none; - margin-top: 0.2em; -} - -dl.field-list > dd { - margin-top: 0.2em; -} - -dl.field-list ul { - list-style: none; -} - -dl.field-list ul li { - list-style: none; - padding-bottom: 0.5em; -} - -dl.field-list.simple dd ul { - padding-left: 0; -} - -dl.field-list.simple dd ul li p:not(:first-child) { - margin-top: 0.4em; -} - -dl.attribute > dd > p { - margin: 0 0 1em 0; -} - -/* NOTE(kgriffs): Fix spacing issue with embedded Note blocks, and make - things generally more readable by spacing the paragraphs. */ -.field-list p { - margin-bottom: 1em; -} - -dl.function, dl.method, dl.attribute, dl.class { - padding-top: 1em; -} - -div.body div.section > ul.simple > li > dl.simple > dd > ul { - margin: 0; -} - -div.body div.toctree-wrapper.compound > ul > li.toctree-l1 > ul { - margin-top: 0; -} - -div.contents.local.topic { - background: none; - border: none; -} - -div.contents.local.topic > ul > li > p { - margin-bottom: 0; -} - -div.contents.local.topic > ul > li > ul { - margin-top: 0; -} - -[role="tablist"] { - border-color: #eee; -} - -.sphinx-tabs-panel { - border-color: #eee; - padding: 4px 1rem; -} - -.sphinx-tabs-tab { - top: 2px; - border-color: #eee; - color: #c77c11; -} - -.sphinx-tabs-tab[aria-selected="true"] { - border-color: #eee; -} - -.sphinx-tabs-tab[aria-selected="false"]:hover { - color: #f0ad4e; - text-decoration: underline; -} - -.sphinx-tabs-tab:focus { - z-index: 0; -} - -.sphinx-tabs-panel .highlight-python { - margin: 4px 0; -} - -div.note, pre { - background-color: rgb(245,245,245); -} - -div.note div.highlight > pre, div.admonition div.highlight > pre { - border: none; -} - -div.note, div.admonition { - /* Match tab radius */ - border-radius: .285714rem; - border-color: #eee; - padding-bottom: 1em; -} - -div.ui.bottom.attached.sphinx-tab.tab { - /* Match tab radius */ - border-bottom-left-radius: .285714rem; - border-bottom-right-radius: .285714rem; -} - -div.highlight > pre { - border: 1px solid #eee; - border-radius: .285714rem; -} - -.sphinx-tab pre { - border: none !important; -} - -/* TODO: remove once alabaster is updated */ -span.descname, span.descclassname { - font-size: 0.95em; +/* Customize the PyData theme's font colors. */ + +/* Some ideas partially inspired by Bokeh docs. */ +html[data-theme=light] { + --pst-color-borders: rgb(206, 212, 218); + --pst-color-primary: var(--pst-color-text-base); + /* Darken Falconry orange to meet WCAG 2.1 AA contrast */ + --pst-color-secondary: rgb(169, 103, 9); + --pst-color-link: var(--pst-color-secondary); + --pst-color-success: rgb(165, 205, 57); + --pst-color-admonition-tip: var(--pst-color-success); + --pst-color-inline-code: var(--pst-color-text-base); + --pst-color-inline-code-links: var(--pst-color-secondary); + --pst-color-surface: rgb(255, 250, 234); +} + +html[data-theme=dark] { + --pst-color-primary: var(--pst-color-text-base); + --pst-color-secondary: rgb(240, 173, 78); + --pst-color-link: var(--pst-color-secondary); + --pst-color-inline-code: var(--pst-color-text-base); + --pst-color-inline-code-links: var(--pst-color-secondary); + --pst-color-background: rgb(8, 6, 2); + --pst-color-on-background: rgb(39, 37, 35); + --pst-color-surface: rgb(31, 31, 31); } diff --git a/docs/api/app.rst b/docs/api/app.rst index b865a2d6f..9e56a4518 100644 --- a/docs/api/app.rst +++ b/docs/api/app.rst @@ -3,10 +3,6 @@ The App Class ============= -* `WSGI App`_ -* `ASGI App`_ -* `Options`_ - Falcon supports both the WSGI (:class:`falcon.App`) and ASGI (:class:`falcon.asgi.App`) protocols. This is done by instantiating the respective ``App`` class to create a diff --git a/docs/api/cookies.rst b/docs/api/cookies.rst index 719e025e4..5089957cc 100644 --- a/docs/api/cookies.rst +++ b/docs/api/cookies.rst @@ -3,7 +3,7 @@ Cookies ------- -.. contents:: :local: +This page describes the API provided by Falcon to manipulate cookies. .. _getting-cookies: @@ -24,9 +24,9 @@ need a collection of all the cookies in the request. Here's an example showing how to get cookies from a request: -.. tabs:: +.. tab-set:: - .. tab:: WSGI + .. tab-item:: WSGI .. code:: python @@ -43,7 +43,7 @@ Here's an example showing how to get cookies from a request: # will need to choose how to handle the additional values. v = my_cookie_values[0] - .. tab:: ASGI + .. tab-item:: ASGI .. code:: python diff --git a/docs/api/cors.rst b/docs/api/cors.rst index d19bf7a78..899278074 100644 --- a/docs/api/cors.rst +++ b/docs/api/cors.rst @@ -29,9 +29,9 @@ can be exposed. Usage ----- -.. tabs:: +.. tab-set:: - .. tab:: WSGI + .. tab-item:: WSGI .. code:: python @@ -45,7 +45,7 @@ Usage app = falcon.App(middleware=falcon.CORSMiddleware( allow_origins='example.com', allow_credentials='*')) - .. tab:: ASGI + .. tab-item:: ASGI .. code:: python diff --git a/docs/api/errors.rst b/docs/api/errors.rst index 462e188a6..528d435e2 100644 --- a/docs/api/errors.rst +++ b/docs/api/errors.rst @@ -3,8 +3,6 @@ Error Handling ============== -.. contents:: :local: - When it comes to error handling, you can always directly set the error status, appropriate response headers, and error body using the ``resp`` object. However, Falcon tries to make things a little easier by @@ -48,9 +46,9 @@ To customize what data is passed to the serializer, subclass All classes are available directly in the ``falcon`` package namespace: -.. tabs:: +.. tab-set:: - .. tab:: WSGI + .. tab-item:: WSGI .. code:: python @@ -68,7 +66,7 @@ All classes are available directly in the ``falcon`` package namespace: # -- snip -- - .. tab:: ASGI + .. tab-item:: ASGI .. code:: python diff --git a/docs/api/hooks.rst b/docs/api/hooks.rst index a3adf4333..91aacd3a5 100644 --- a/docs/api/hooks.rst +++ b/docs/api/hooks.rst @@ -3,9 +3,6 @@ Hooks ===== -* `Before Hooks`_ -* `After Hooks`_ - Falcon supports *before* and *after* hooks. You install a hook simply by applying one of the decorators below, either to an individual responder or to an entire resource. diff --git a/docs/api/inspect.rst b/docs/api/inspect.rst index 48cbfaec5..7e3d46283 100644 --- a/docs/api/inspect.rst +++ b/docs/api/inspect.rst @@ -3,12 +3,6 @@ Inspect Module ============== -* `Using Inspect Functions`_ -* `Inspect Functions Reference`_ -* `Router Inspection`_ -* `Information Classes`_ -* `Visitor Classes`_ - This module can be used to inspect a Falcon application to obtain information about its registered routes, middleware objects, static routes, sinks and error handlers. The entire application can be inspected at once using the diff --git a/docs/api/media.rst b/docs/api/media.rst index dbff05383..ac8105d9f 100644 --- a/docs/api/media.rst +++ b/docs/api/media.rst @@ -3,8 +3,6 @@ Media ===== -.. contents:: :local: - Falcon allows for easy and customizable internet media type handling. By default Falcon only enables handlers for JSON and HTML (URL-encoded and multipart) forms. However, additional handlers can be configured through the @@ -26,9 +24,9 @@ Zero configuration is needed if you're creating a JSON API. Simply use :attr:`~falcon.asgi.Response.media` (ASGI) to let Falcon do the heavy lifting for you. -.. tabs:: +.. tab-set:: - .. tab:: WSGI + .. tab-item:: WSGI .. code:: python @@ -52,7 +50,7 @@ do the heavy lifting for you. resp.media = {'message': message} resp.status = falcon.HTTP_200 - .. tab:: ASGI + .. tab-item:: ASGI .. code:: python @@ -109,9 +107,9 @@ response. If you do need full negotiation, it is very easy to bridge the gap using middleware. Here is an example of how this can be done: -.. tabs:: +.. tab-set:: - .. tab:: WSGI + .. tab-item:: WSGI .. code:: python @@ -121,7 +119,7 @@ middleware. Here is an example of how this can be done: def process_request(self, req: Request, resp: Response) -> None: resp.content_type = req.accept - .. tab:: ASGI + .. tab-item:: ASGI .. code:: python diff --git a/docs/api/middleware.rst b/docs/api/middleware.rst index 3cfbb18cd..251e8e8c0 100644 --- a/docs/api/middleware.rst +++ b/docs/api/middleware.rst @@ -3,8 +3,6 @@ Middleware ========== -.. contents:: :local: - Middleware components provide a way to execute logic before the framework routes each request, after each request is routed but before the target responder is called, or just before the response is returned @@ -18,9 +16,9 @@ when instantiating Falcon's :ref:`App class `. A middleware component is simply a class that implements one or more of the event handler methods defined below. -.. tabs:: +.. tab-set:: - .. tab:: WSGI + .. tab-item:: WSGI Falcon's middleware interface is defined as follows: @@ -96,7 +94,7 @@ defined below. app = App(middleware=[ExampleMiddleware()]) - .. tab:: ASGI + .. tab-item:: ASGI The ASGI middleware interface is similar to WSGI, but also supports the standard ASGI lifespan events. However, because lifespan events are an diff --git a/docs/api/multipart.rst b/docs/api/multipart.rst index cf2620414..a4bb664cf 100644 --- a/docs/api/multipart.rst +++ b/docs/api/multipart.rst @@ -3,17 +3,16 @@ Multipart Forms =============== -.. contents:: :local: - Falcon features easy and efficient access to submitted multipart forms by using :class:`~falcon.media.MultipartFormHandler` to handle the ``multipart/form-data`` :ref:`media ` type. This handler is enabled by default, allowing you to use ``req.get_media()`` to iterate over the :class:`body parts ` in a form: -.. tabs:: +.. tab-set:: - .. group-tab:: WSGI + .. tab-item:: WSGI + :sync: wsgi .. code:: python @@ -38,7 +37,8 @@ default, allowing you to use ``req.get_media()`` to iterate over the # Do something else form_data[part.name] = part.text - .. group-tab:: ASGI + .. tab-item:: ASGI + :sync: asgi .. code:: python @@ -72,9 +72,10 @@ default, allowing you to use ``req.get_media()`` to iterate over the Multipart Form and Body Part Types ---------------------------------- -.. tabs:: +.. tab-set:: - .. group-tab:: WSGI + .. tab-item:: WSGI + :sync: wsgi .. autoclass:: falcon.media.multipart.MultipartForm :members: @@ -82,7 +83,8 @@ Multipart Form and Body Part Types .. autoclass:: falcon.media.multipart.BodyPart :members: - .. group-tab:: ASGI + .. tab-item:: ASGI + :sync: asgi .. autoclass:: falcon.asgi.multipart.MultipartForm :members: @@ -126,9 +128,10 @@ way is to directly modify the properties of this attribute on the media handler In order to use your customized handler in an app, simply replace the default handler for ``multipart/form-data`` with the new one: -.. tabs:: +.. tab-set:: - .. group-tab:: WSGI + .. tab-item:: WSGI + :sync: wsgi .. code:: python @@ -137,7 +140,8 @@ handler for ``multipart/form-data`` with the new one: # handler is instantiated and configured as per the above snippet app.req_options.media_handlers[falcon.MEDIA_MULTIPART] = handler - .. group-tab:: ASGI + .. tab-item:: ASGI + :sync: asgi .. code:: python diff --git a/docs/api/request_and_response_asgi.rst b/docs/api/request_and_response_asgi.rst index 8d7d154cc..579d3d664 100644 --- a/docs/api/request_and_response_asgi.rst +++ b/docs/api/request_and_response_asgi.rst @@ -3,9 +3,6 @@ ASGI Request & Response ======================= -* `Request`_ -* `Response`_ - Instances of the :class:`falcon.asgi.Request` and :class:`falcon.asgi.Response` classes are passed into responders as the second and third arguments, respectively: diff --git a/docs/api/request_and_response_wsgi.rst b/docs/api/request_and_response_wsgi.rst index 540f26f42..3b715b643 100644 --- a/docs/api/request_and_response_wsgi.rst +++ b/docs/api/request_and_response_wsgi.rst @@ -3,9 +3,6 @@ WSGI Request & Response ======================= -* `Request`_ -* `Response`_ - Instances of the :class:`falcon.Request` and :class:`falcon.Response` classes are passed into WSGI app responders as the second and third arguments, respectively: diff --git a/docs/api/routing.rst b/docs/api/routing.rst index 347b3516d..4d339c9da 100644 --- a/docs/api/routing.rst +++ b/docs/api/routing.rst @@ -3,8 +3,6 @@ Routing ======= -.. contents:: :local: - Falcon uses resource-based routing to encourage a RESTful architectural style. Each resource is represented by a class that is responsible for handling all of the HTTP methods that the resource supports. @@ -29,9 +27,9 @@ associated resource for processing. Here's a quick example to show how all the pieces fit together: -.. tabs:: +.. tab-set:: - .. tab:: WSGI + .. tab-item:: WSGI .. code:: python @@ -66,7 +64,7 @@ Here's a quick example to show how all the pieces fit together: images = ImagesResource() app.add_route('/images', images) - .. tab:: ASGI + .. tab-item:: ASGI .. code:: python @@ -205,9 +203,9 @@ A PUT request to ``'/user/kgriffs'`` would cause the framework to invoke the ``on_put()`` responder method on the route's resource class, passing ``'kgriffs'`` via an additional `name` argument defined by the responder: -.. tabs:: +.. tab-set:: - .. tab:: WSGI + .. tab-item:: WSGI .. code:: python @@ -216,7 +214,7 @@ the ``on_put()`` responder method on the route's resource class, passing def on_put(self, req, resp, name): pass - .. tab:: ASGI + .. tab-item:: ASGI .. code:: python @@ -511,9 +509,9 @@ support custom HTTP methods, use one of the following methods: Once you have used the appropriate method, your custom methods should be active. You then can define request methods like any other HTTP method: -.. tabs:: +.. tab-set:: - .. tab:: WSGI + .. tab-item:: WSGI .. code:: python @@ -521,7 +519,7 @@ You then can define request methods like any other HTTP method: def on_foo(self, req, resp): pass - .. tab:: ASGI + .. tab-item:: ASGI .. code:: python diff --git a/docs/api/status.rst b/docs/api/status.rst index 449b2a071..13f6a1fd3 100644 --- a/docs/api/status.rst +++ b/docs/api/status.rst @@ -3,8 +3,6 @@ Status Codes ============ -.. contents:: :local: - Falcon provides a list of constants for common `HTTP response status codes `_. diff --git a/docs/api/testing.rst b/docs/api/testing.rst index c68267d35..67357cb52 100644 --- a/docs/api/testing.rst +++ b/docs/api/testing.rst @@ -3,8 +3,6 @@ Testing Helpers =============== -.. contents:: :local: - .. automodule:: falcon.testing :noindex: diff --git a/docs/api/util.rst b/docs/api/util.rst index d5dce81cb..810790448 100644 --- a/docs/api/util.rst +++ b/docs/api/util.rst @@ -3,7 +3,7 @@ Utilities ========= -.. contents:: :local: +This page describes miscellaneous utilities provided by Falcon. URI --- diff --git a/docs/api/websocket.rst b/docs/api/websocket.rst index b3bf42c05..6e632c521 100644 --- a/docs/api/websocket.rst +++ b/docs/api/websocket.rst @@ -3,8 +3,6 @@ WebSocket (ASGI Only) ===================== -.. contents:: :local: - Falcon builds upon the `ASGI WebSocket Specification `_ to provide a simple, no-nonsense WebSocket server implementation. diff --git a/docs/conf.py b/docs/conf.py index abd0a92c5..492c0028d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,17 +1,23 @@ -# Falcon documentation build configuration file, created by -# sphinx-quickstart on Wed Mar 12 14:14:02 2014. +# Copyright 2014-2024 by Falcon Contributors. # -# This file is execfile()d with the current directory set to its -# containing dir. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at # -# Note that not all possible configuration values are present in this -# autogenerated file. +# http://www.apache.org/licenses/LICENSE-2.0 # -# All configuration values have a default; values that are commented out -# serve to show the default. +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. -from collections import OrderedDict -from datetime import datetime +# 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 datetime import multiprocessing import os import sys @@ -20,6 +26,8 @@ import falcon # noqa: E402 +# -- Build tweaks ------------------------------------------------------------- + # NOTE(kgriffs): Work around the change in Python 3.8 that breaks sphinx # on macOS. See also: # @@ -29,11 +37,11 @@ if not sys.platform.startswith('win'): multiprocessing.set_start_method('fork') -# on_rtd is whether we are on readthedocs.org -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +# _on_rtd is whether we are on readthedocs.org +# _on_rtd = os.environ.get('READTHEDOCS', None) == 'True' # Used to alter sphinx configuration for the Dash documentation build -dash_build = os.environ.get('DASHBUILD', False) == 'True' +_dash_build = os.environ.get('DASHBUILD', False) == 'True' # 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 @@ -41,24 +49,32 @@ sys.path.insert(0, os.path.abspath('..')) sys.path.insert(0, os.path.abspath('.')) -# Path to custom themes -sys.path.append(os.path.abspath('_themes')) +# -- Project information ------------------------------------------------------ +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -# -- General configuration ------------------------------------------------ +_version_components = falcon.__version__.split('.') +_prerelease_version = any( + not component.isdigit() and not component.startswith('post') + for component in _version_components +) + + +project = 'Falcon' +copyright = '{year} Falcon Contributors'.format(year=datetime.datetime.now().year) +author = 'Kurt Griffiths et al.' +version = '.'.join(_version_components[0:2]) +release = falcon.__version__ -# If your documentation needs a minimal Sphinx version, state it here. -# needs_sphinx = '1.0' +# -- General configuration ---------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = [ - 'sphinx.ext.intersphinx', 'sphinx.ext.autodoc', - 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon', - 'sphinx_tabs.tabs', - 'sphinx_tabs.tabs', + 'sphinx.ext.viewcode', + 'sphinx_copybutton', + 'sphinx_design', 'myst_parser', # Falcon-specific extensions 'ext.cibuildwheel', @@ -67,232 +83,99 @@ 'ext.rfc', ] -# 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 = 'Falcon' -copyright = '{year} Falcon Contributors'.format(year=datetime.now().year) - -# 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. - -_version_components = falcon.__version__.split('.') -_prerelease = any( - not component.isdigit() and not component.startswith('post') - for component in _version_components -) - -html_context = {'prerelease': _prerelease} - -# The short X.Y version. -version = '.'.join(_version_components[0:2]) - -# The full version, including alpha/beta/rc tags. -release = falcon.__version__ - -# 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', '_newsfragments'] -# 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 = 'github' - -# 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 - - -# -- Options for HTML output ---------------------------------------------- +# NOTE(vytas): The PyData theme uses separate Pygments style settings for HTML, +# so we specify a print-friendly theme here for the likes of latexpdf. +pygments_style = 'bw' -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = ['_themes'] -# html_theme = '' - -html_theme = 'alabaster' - -# if not on_rtd: -# # Use the RTD theme explicitly if it is available -# try: -# import sphinx_rtd_theme - -# html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -# html_theme = "sphinx_rtd_theme" -# except ImportError: -# pass - -# 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 = { - 'page_width': '80%', - 'body_max_width': '100%', - 'github_user': 'falconry', - 'github_repo': 'falcon', - 'github_button': False, - 'github_banner': False, - 'fixed_sidebar': False, - 'show_powered_by': False, - 'extra_nav_links': OrderedDict( - [ - ('Falcon Home', 'https://falconframework.org/'), - ('Falcon Wiki', 'https://github.com/falconry/falcon/wiki'), - ('GitHub Project', 'https://github.com/falconry/falcon'), - ('Get Help', '/community/help.html'), - ( - 'Support Falcon', - 'https://falconframework.org/#sectionSupportFalconDevelopment', - ), - ] - ), -} - -if dash_build: - html_theme_options.update( - { - 'font_size': 13, - } - ) - -# 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 +# Intersphinx configuration +intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# html_logo = '../falcon.png' +# -- Options for HTML output -------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -# 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_css_files = ['custom.css'] +html_js_files = ['custom-icons.js'] html_favicon = '_static/img/favicon.ico' - -# 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_logo = '_static/img/logo.svg' 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 = { -# 'index': ['side-primary.html', 'searchbox.html'], -# '**': ['side-secondary.html', 'localtoc.html', -# 'relations.html', 'searchbox.html'] -# } - -html_sidebars = { - '**': [ - 'sidebar-top.html', - 'sidebar-sponsors.html', - 'about.html', - 'navigation.html', - 'relations.html', - 'searchbox.html', - ] - if not dash_build - else [] +html_theme = 'pydata_sphinx_theme' +html_show_sourcelink = False + +html_context = { + # NOTE(vytas): We don't provide any default, the browser's preference + # should be used. + # 'default_mode': 'light', + 'prerelease': _prerelease_version, # True if tag is not the empty string } -# 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 +# Theme options are theme-specific and customize the look and feel further. +# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/index.html -# 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 = '' +html_theme_options = { + 'pygments_light_style': 'falconry-light', + 'pygments_dark_style': 'falconry-dark', + 'header_links_before_dropdown': 4, + 'external_links': [ + { + 'name': 'Get Help', + 'url': 'https://falcon.readthedocs.io/community/help.html', + }, + {'name': 'Falcon Wiki', 'url': 'https://github.com/falconry/falcon/wiki'}, + { + 'name': 'Support Falcon', + 'url': 'https://falconframework.org/#sectionSupportFalconDevelopment', + }, + ], + 'icon_links': [ + { + 'name': 'GitHub', + 'url': 'https://github.com/falconry/falcon', + 'icon': 'fa-brands fa-github', + }, + { + 'name': 'PyPI', + 'url': 'https://pypi.org/project/falcon', + 'icon': 'fa-custom fa-pypi', + }, + { + 'name': 'Falcon Home', + 'url': 'https://falconframework.org', + 'icon': 'fa-custom fa-falcon', + }, + ], + # NOTE(vytas): Use only light theme for now. + # Add `theme-switcher` below to resurrect the dark option. + 'logo': { + 'text': 'Falcon', + # "image_dark": "_static/img/logo.svg", + }, + 'navbar_end': ['theme-switcher', 'navbar-icon-links'], + 'footer_start': ['copyright'], + 'footer_end': ['theme-version'], +} -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None +if _dash_build: + html_theme_options.update(font_size=13) -# Output file base name for HTML help builder. -htmlhelp_basename = 'Falcondoc' +# -- Options for LaTeX output ------------------------------------------------- -# -- Options for LaTeX output --------------------------------------------- +# NOTE(vytas): The default engine fails to build citing unsupported Unicode +# characters. +latex_engine = 'xelatex' latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # 'papersize': 'letterpaper', + 'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). # 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. # 'preamble': '', } -# 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', @@ -303,42 +186,12 @@ ), ] -# 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 ------------------------------------------- - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). man_pages = [('index', 'falcon', 'Falcon Documentation', ['Kurt Griffiths et al.'], 1)] -# If true, show URL addresses after external links. -# man_show_urls = False - +# -- Options for Texinfo output ----------------------------------------------- -# -- 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', @@ -350,18 +203,3 @@ '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 - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} diff --git a/docs/index.rst b/docs/index.rst index 8e3ac1f0d..359062b5f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,7 +21,6 @@ while remaining highly effective. import falcon class QuoteResource: - def on_get(self, req, resp): """Handles GET requests""" quote = { @@ -128,7 +127,7 @@ Documentation :maxdepth: 3 user/index - deploy/index community/index api/index changes/index + deploy/index diff --git a/docs/user/faq.rst b/docs/user/faq.rst index 11a394b63..56826fbe0 100644 --- a/docs/user/faq.rst +++ b/docs/user/faq.rst @@ -3,8 +3,6 @@ FAQ === -.. contents:: :local: - Design Philosophy ~~~~~~~~~~~~~~~~~ @@ -689,9 +687,10 @@ The `stream` of a body part is a file-like object implementing the ``read()`` method, making it compatible with ``boto3``\'s `upload_fileobj `_: -.. tabs:: +.. tab-set:: - .. group-tab:: WSGI + .. tab-item:: WSGI + :sync: wsgi .. code:: python @@ -705,7 +704,8 @@ method, making it compatible with ``boto3``\'s if part.name == 'myfile': s3.upload_fileobj(part.stream, 'mybucket', 'mykey') - .. group-tab:: ASGI + .. tab-item:: ASGI + :sync: asgi .. code:: python diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index 43157ac9f..38f0f88c7 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -13,9 +13,10 @@ Learning by Example Here is a simple example from Falcon's README, showing how to get started writing an app. -.. tabs:: +.. tab-set:: - .. group-tab:: WSGI + .. tab-item:: WSGI + :sync: wsgi .. literalinclude:: ../../examples/things.py :language: python @@ -41,7 +42,8 @@ started writing an app. $ pip install --upgrade httpie $ http localhost:8000/things - .. group-tab:: ASGI + .. tab-item:: ASGI + :sync: asgi .. literalinclude:: ../../examples/things_asgi.py :language: python @@ -75,9 +77,10 @@ A More Complex Example Here is a more involved example that demonstrates reading headers and query parameters, handling errors, and working with request and response bodies. -.. tabs:: +.. tab-set:: - .. group-tab:: WSGI + .. tab-item:: WSGI + :sync: wsgi Note that this example assumes that the `requests `_ package has been installed. @@ -135,7 +138,8 @@ parameters, handling errors, and working with request and response bodies. • Error handlers: ⇜ StorageError handle - .. group-tab:: ASGI + .. tab-item:: ASGI + :sync: asgi Note that this example requires the `httpx `_ package in lieu of diff --git a/docs/user/recipes/output-csv.rst b/docs/user/recipes/output-csv.rst index 42556253b..8f3f8b948 100644 --- a/docs/user/recipes/output-csv.rst +++ b/docs/user/recipes/output-csv.rst @@ -9,14 +9,16 @@ file is a fairly common back-end service task. The easiest approach is to simply write CSV rows to an ``io.StringIO`` stream, and then assign its value to :attr:`resp.text `: -.. tabs:: +.. tab-set:: - .. group-tab:: WSGI + .. tab-item:: WSGI + :sync: wsgi .. literalinclude:: ../../../examples/recipes/output_csv_text_wsgi.py :language: python - .. group-tab:: ASGI + .. tab-item:: ASGI + :sync: asgi .. literalinclude:: ../../../examples/recipes/output_csv_text_asgi.py :language: python @@ -38,14 +40,16 @@ our own pseudo stream object. Our stream's ``write()`` method will simply accumulate the CSV data in a list. We will then set :attr:`resp.stream ` to a generator yielding data chunks from this list: -.. tabs:: +.. tab-set:: - .. group-tab:: WSGI + .. tab-item:: WSGI + :sync: wsgi .. literalinclude:: ../../../examples/recipes/output_csv_stream_wsgi.py :language: python - .. group-tab:: ASGI + .. tab-item:: ASGI + :sync: asgi .. literalinclude:: ../../../examples/recipes/output_csv_stream_wsgi.py :language: python diff --git a/falcon/media/validators/jsonschema.py b/falcon/media/validators/jsonschema.py index 8fc53ade9..0e6f14b67 100644 --- a/falcon/media/validators/jsonschema.py +++ b/falcon/media/validators/jsonschema.py @@ -56,9 +56,9 @@ def validate(req_schema=None, resp_schema=None, is_async=False): Example: - .. tabs:: + .. tab-set:: - .. tab:: WSGI + .. tab-item:: WSGI .. code:: python @@ -71,7 +71,7 @@ def on_post(self, req, resp): # -- snip -- - .. tab:: ASGI + .. tab-item:: ASGI .. code:: python @@ -84,7 +84,7 @@ async def on_post(self, req, resp): # -- snip -- - .. tab:: ASGI (Cythonized App) + .. tab-item:: ASGI (Cythonized App) .. code:: python diff --git a/requirements/docs b/requirements/docs index 4e4fece59..1eb338fb8 100644 --- a/requirements/docs +++ b/requirements/docs @@ -1,11 +1,8 @@ -docutils doc2dash -jinja2 -markupsafe -pygments +falconry-pygments-theme >= 0.2.0 myst-parser -pygments-style-github +pydata-sphinx-theme PyYAML -sphinx -sphinx_rtd_theme -sphinx-tabs +Sphinx +sphinx-copybutton +sphinx_design