From 9d2c7a8a0c71b911efc3beaec590f78011a6125b Mon Sep 17 00:00:00 2001 From: Rambaud Pierrick <12rambau@users.noreply.github.com> Date: Thu, 19 Jan 2023 06:51:00 +0100 Subject: [PATCH] update documentation (#27) * use nox add nox to run test and mypy in isolated environment * use the complete python gitignore I faced some issue while building the nox, I think you can afford the full gitignore suggested by github * add mypy check in nox * use extra-require to build the test * add a mypy check in the github actions * reduce the number of tests linux test all the python version so windows and macos should only test 1 * forgot to reset pre-commit * reduce number of test again * build the doc with nox also drop requirement files * remove make files * use pydata-sphinx-theme for the doc * use copybutton * typo in icons names * refactoring * reduce readme to minimum * add a breaking change note * add a python version badge basd on the pypi classifiers * add a favicon to our doc * typo in project name * add an announcment banner * tune doc environment * Add pre-commit to dev dependencies * Small updates to README * Add lint session to nox * Remove print() * Update and expand RST docs Co-authored-by: tcmetzger <39711796+tcmetzger@users.noreply.github.com> --- .readthedocs.yml | 9 +- README.md | 192 ++----------- dev-requirements.txt | 6 - docs-requirements.txt | 4 - docs/Makefile | 20 -- docs/make.bat | 35 --- .../source/_static/android-chrome-192x192.png | Bin 0 -> 6363 bytes docs/source/_static/announcment.html | 3 + docs/source/_static/apple-touch-icon.png | Bin 0 -> 4843 bytes docs/source/_static/browserconfig.xml | 9 + docs/source/_static/custom.css | 21 ++ docs/source/_static/favicon-16x16.png | Bin 0 -> 608 bytes docs/source/_static/favicon-32x32.png | Bin 0 -> 1029 bytes docs/source/_static/favicon.ico | Bin 0 -> 15086 bytes docs/source/_static/mstile-150x150.png | Bin 0 -> 4546 bytes docs/source/_static/safari-pinned-tab.svg | 33 +++ docs/source/_static/site.webmanifest | 14 + docs/source/conf.py | 83 ++++-- docs/source/index.rst | 265 +++++++++++++++++- noxfile.py | 16 +- setup.cfg | 5 +- sphinx_favicon/__init__.py | 1 - 22 files changed, 435 insertions(+), 281 deletions(-) delete mode 100644 dev-requirements.txt delete mode 100644 docs-requirements.txt delete mode 100644 docs/Makefile delete mode 100644 docs/make.bat create mode 100644 docs/source/_static/android-chrome-192x192.png create mode 100644 docs/source/_static/announcment.html create mode 100644 docs/source/_static/apple-touch-icon.png create mode 100644 docs/source/_static/browserconfig.xml create mode 100644 docs/source/_static/custom.css create mode 100644 docs/source/_static/favicon-16x16.png create mode 100644 docs/source/_static/favicon-32x32.png create mode 100644 docs/source/_static/favicon.ico create mode 100644 docs/source/_static/mstile-150x150.png create mode 100644 docs/source/_static/safari-pinned-tab.svg create mode 100644 docs/source/_static/site.webmanifest diff --git a/.readthedocs.yml b/.readthedocs.yml index f058036..fc91d7a 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -15,11 +15,8 @@ build: sphinx: configuration: docs/source/conf.py -# If using Sphinx, optionally build your docs in additional formats such as PDF -# formats: -# - pdf - # Optionally declare the Python requirements required to build your docs python: - install: - - requirements: docs-requirements.txt + install: + - method: pip + path: .[doc] diff --git a/README.md b/README.md index 307e232..7b4622b 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,13 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Black badge](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![PyPI](https://img.shields.io/pypi/v/sphinx-favicon?logo=python&logoColor=white)](https://pypi.org/project/sphinx-favicon/) +![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sphinx-favicon?color=orange&logo=python&logoColor=white) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/tcmetzger/sphinx-favicon/basic-ci.yml?logo=github&logoColor=white) -[![Documentation Status](https://readthedocs.org/projects/sphinx-favicon/badge/?version=latest)](https://sphinx-favicon.readthedocs.io/en/latest/?badge=latest) +![Read the Docs (version)](https://img.shields.io/readthedocs/sphinx-favicon/latest?logo=readthedocs&logoColor=white) + +> **Note** +> **Updating from v0.2 to v0.3.** +> When moving from v0.2 to v0.3 the name of the extention was changed. Please update the name used in the extention list of your `conf.py` from `sphinx-favicon` to `sphinx_favicon`. **A Sphinx extension to add custom favicons** @@ -17,7 +22,7 @@ or [`"apple-touch-icon"`](https://developer.apple.com/library/archive/documentat any favicon size. The Sphinx Favicon extension gives you more flexibility than the [standard -`favicon.ico` supported by Sphinx](https://www.sphinx-doc.org/en/master/templating.html?highlight=favicon#favicon_url). It provides a quick and easy way to add the most +`favicon.ico` supported by Sphinx](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_favicon). It provides a quick and easy way to add the most important favicon formats for different browsers and devices. ## Installation @@ -30,80 +35,29 @@ pip install sphinx-favicon ## Usage -After installing Sphinx Favicon, you can configure the extension directly in -`conf.py` (see [Configuration](https://www.sphinx-doc.org/en/master/usage/configuration.html) -in the Sphinx documentation for more information about this file). - -There are two ways to include favicon files in your configuration: - -* Either use an **absolute URL** for a favicon file (beginning with `http://` or - `https://`). If you use an absolute URL, use the `"href"` parameter. See below - for examples. -* Or use a **local static file** as a favicon. Make sure you place your local - static favicon file(s) inside a directory listed in [Sphinx' `html_static_path`](https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=static#confval-html_static_path). If you use a relative path, use the `"static-file"` parameter. See below for - examples. - -To configure Sphinx Favicon, first add `"sphinx_favicon"` to the list of -extensions: +After installing **sphinx-favicon**, add it to your `conf.py` extension list: ```python -extensions = [ - "sphinx_favicon", -] +extensions = ["sphinx_favicon"] ``` -Next, you have several options to define favicons: - -### Option A: Provide detailed metadata as a list of dicts - -Use a list of dicts for maximum control over the favicons added to your html -document. You can use the following parameters to define a favicon: - -* ``rel``: a value for the favicon's ``rel`` attribute, usually either the -standard [`"icon"`](https://html.spec.whatwg.org/multipage/links.html#rel-icon) -or a custom extension like [`"apple-touch-icon"`](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html) -* ``sizes``: a value for the [favicon's ``sizes`` attribute](https://html.spec.whatwg.org/multipage/semantics.html#attr-link-sizes) -* ``href``: the **absolute URL** to the favicon's image file (not required if you use the ``static-file`` parameter, see below) -* ``type``: a value specifying the [favicon's MIME type](https://html.spec.whatwg.org/multipage/semantics.html#attr-link-type) -* ``static-file``: the **local static file** corresponding to your icon's image. - Please notice this path should be relative to a directory listed in - [Sphinx' `html_static_path`](https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=static#confval-html_static_path) (usually `_static`). If you define both - ``static-file`` and ``href``, the value for ``href`` will be ignored. - -For example: +Then configure the favicon links using the `favicons` parameter (`html_static_path` is mandatory if you use relative path): ```python -html_static_path = ["_static"] # html_static_path is required if you use the "static-file" parameter +html_static_path = ["_static"] favicons = [ - { - "rel": "icon", - "static-file": "icon.svg", # => use `_static/icon.svg` - "type": "image/svg+xml", - }, - { - "rel": "icon", - "sizes": "16x16", - "href": "https://secure.example.com/favicon/favicon-16x16.png", - "type": "image/png", - }, - { - "rel": "icon", - "sizes": "32x32", - "href": "https://secure.example.com/favicon/favicon-32x32.png", - "type": "image/png", - }, + {"static-file": "icon.svg"}, # => use `_static/icon.svg` + {"href": "https://secure.example.com/favicon/favicon-16x16.png"}, + {"href": "https://secure.example.com/favicon/favicon-32x32.png"}, { "rel": "apple-touch-icon", - "sizes": "180x180", "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png", - "type": "image/png", }, ] ``` -Based on this configuration, Sphinx will include the following favicon -information in the HTML `` element: +Based on this configuration, Sphinx will include the following favicon information in the HTML `` element: ```html @@ -112,115 +66,11 @@ information in the HTML `` element: ``` -Note that the relative path to the favicon's image file in the static directory -will be adjusted according to each html file's location. - -To make things easier for you, Sphinx Favicon can also add *some* metadata to -each favicon's `` element automatically: - -* If you don't provide the `"rel"` argument, Sphinx Favicon automatically adds -`rel="icon"`. -* if you don't provide the `"type"` argument, Sphinx Favicon automatically -determines the MIME type based on the image's filename extension. -* Currently, Sphinx Favicon is not able to automatically read a file's size in -pixels as required for the `"size"` argument. If you don't provide information -about a favicon file's pixel size, the `"size"` argument will be omitted for -that favicon image. - -Therefore, the following simplified configuration generates the exact same -HTML result as above: - -```python -html_static_path = ["_static"] - -favicons = [ - {"static-file": "icon.svg"}, # => use `_static/icon.svg` - { - "sizes": "16x16", - "href": "https://secure.example.com/favicon/favicon-16x16.png", - }, - { - "sizes": "32x32", - "href": "https://secure.example.com/favicon/favicon-32x32.png", - }, - { - "rel": "apple-touch-icon", - "sizes": "180x180", - "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png", - }, -] -``` - -### Option B: Provide a single dict for just one favicon - -If you want to add just one custom favicon, you can also use a simple dict in -`conf.py`: - -```python -favicons = { - "rel": "apple-touch-icon", - "sizes": "180x180", - "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png", - } -``` - -Based on this configuration, Sphinx will include the following favicon -information in the `` of every HTML file: - -```html - -``` - -### Option C: Provide a list of local favicon files or URLs - -The quickest way to add favicons is just adding a list of favicon URLs to -`conf.py`. - -```python -html_static_path = ["_static"] -favicons = [ - "icon.svg", # => `_static_/icon.svg` - "https://secure.example.com/favicon/favicon-16x16.gif", - "https://secure.example.com/favicon/favicon-32x32.png", - "https://secure.example.com/favicon/apple-touch-icon-180x180.png", -] -``` - -Based on this configuration, Sphinx will include the following favicon -information in the HTML `` element: - -```html - - - - -``` - -Please note that if your URLs don't start with `https://`, `http://` or `/`, -they will be considered a static file inside a directory listed in -[Sphinx' `html_static_path`](https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=static#confval-html_static_path). - -## Contribute - -To contribute to this extension, please open an issue or make a pull request to -the repository on GitHub. - -### Contributing to the codebase - -Additional dependencies for development are listed in the file -`dev-requirements.txt` in the repository. -Run `pip install -r dev-requirements.txt` to set up your environment, followed -by `pre-commit install`. -Using a [virtual environment](https://docs.python.org/3/tutorial/venv.html) is -recommended. - -After installing the rev requirements, run ``pytest -vv`` to run tests. - -### Contributing to the docs - -The documentation uses [Sphinx](https://www.sphinx-doc.org/en/master/). +For more details and more advanced usage, please see the +[documentation](https://sphinx-favicon.readthedocs.io/en/stable). -To set up your environment to build the docs, run -`pip install -r docs-requirements.txt`. +## Contribution -To build the docs locally, enter the directory `docs` and run `make html`. +Contributions of any kind are welcome. Please see the +[contribution](https://sphinx-favicon.readthedocs.io/en/stable#Contribute) section of +our documntation for more information. diff --git a/dev-requirements.txt b/dev-requirements.txt deleted file mode 100644 index 8c51106..0000000 --- a/dev-requirements.txt +++ /dev/null @@ -1,6 +0,0 @@ --e . -beautifulsoup4 -pre-commit -pytest -setuptools -sphinx diff --git a/docs-requirements.txt b/docs-requirements.txt deleted file mode 100644 index 7fce772..0000000 --- a/docs-requirements.txt +++ /dev/null @@ -1,4 +0,0 @@ -. -myst-parser -sphinx -sphinx_rtd_theme diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index dc1312a..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/_static/android-chrome-192x192.png b/docs/source/_static/android-chrome-192x192.png new file mode 100644 index 0000000000000000000000000000000000000000..f319efa4d0ffd5bbb5831f6d5a81a928f4422b30 GIT binary patch literal 6363 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 xpK!_tRr>dO$47p(6WY1kZ}o<%ZS?>E literal 0 HcmV?d00001 diff --git a/docs/source/_static/announcment.html b/docs/source/_static/announcment.html new file mode 100644 index 0000000..cc5ceb8 --- /dev/null +++ b/docs/source/_static/announcment.html @@ -0,0 +1,3 @@ +

+ When moving from v0.2 to v0.3 the name of the extention was changed. Please update the name used in the extention list of your conf.py from sphinx-favicon to sphinx_favicon. +

\ No newline at end of file diff --git a/docs/source/_static/apple-touch-icon.png b/docs/source/_static/apple-touch-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..1adb4343d8520cbe560203c2d899b0687ce756c9 GIT binary patch literal 4843 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 O0BXwG&uXF8G5-TzZ6cfi literal 0 HcmV?d00001 diff --git a/docs/source/_static/browserconfig.xml b/docs/source/_static/browserconfig.xml new file mode 100644 index 0000000..a47e5a5 --- /dev/null +++ b/docs/source/_static/browserconfig.xml @@ -0,0 +1,9 @@ + + + + + + #2d89ef + + + diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..f66af7b --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,21 @@ +/* add dollar sign in console code-block */ +div.highlight-console pre span.go::before { + /*-webkit-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + -o-user-select: none; + user-select: none;*/ + content: "$"; + margin-right: 10px; + margin-left: 5px; +} + +/* make the footer inline */ +.footer-item { + display: inline-block; +} +.footer-item:not(:last-child) { + border-right: 1px solid var(--pst-color-text-base); + margin-right: 0.5em; + padding-right: 0.5em; +} \ No newline at end of file diff --git a/docs/source/_static/favicon-16x16.png b/docs/source/_static/favicon-16x16.png new file mode 100644 index 0000000000000000000000000000000000000000..f008a6b98731ad809f9c33276203bcfbf92d7ca4 GIT binary patch literal 608 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!60wlNoGJgf6SkfJR9T^xl_H+M9WCijSl0AZa z85pY67#JE_7#My5g&JNkFq9fFFuY1&V6d9Oz#v{QXIG#NP=YDR+ueoXe|!I#{Xiaj ziKnkC`*TJ<4h6<b<3#+9AQ=Oyk?wB4v zAwZNIV9C061uNEHze@a_ul(8jN2VOCtP|FnhXph)e_f;l9a@f zRIB8oR3OD*WME{hYhb8rXcA&zVP$M&WnidnU|?lnaN*OU(k4UEa{HEjtmSN`?>!lvVtU&J%W50 z7^>757#dm_7=8hT8eT9klo~KFyh>nTu$sZZAYL$MSD+10f+@+{-G$+Qd;gjJKpuOE zr>`sfb4ET61;%f?W=#dkukv(p4DmSr_KJ7Tl~fVd5BE!!Exk0&OWrASX4n#sRa+Kv zEOKQPzt$`Dxa$Zj=bHfWT}8<%nUA*Vm`Iu1J#tfae0{8!-^tMHme=8koQWcfrf}sR zpJeyK=XtT=UoFowfDWqC-8O*|uh~YSv!6 zt?{ZY@UPG^QO>^IQ?BNJSlPnaeM#@vrEIxC-B-+x0x{de@6^ffR8aN!eR_%{`!t?y z66XVtm)>4$5?+6?N8yJbZ^Y9`XUjB$)zLb?xxZHgx4UJ#un3>Cdb%ai^ZW~wXSMq? zHyjS0cVPj?blJ~4jVF0m2P`?2#{Y7I@$}+bOAN!$LAgSD*w1}E82YH$+%v(Gh2JPzqMGt z)XiML+=-rfXVO`BBwR(w? z{pZhA?_E&ap3h=`lXDk~vQ<%{-r}1()=ypWeaENSuTuGTDLmexyC9_h!Hcyg!(STb z`NzH0^S64|rWw1cc&p!JvA6LrKg3Nnd&E2U*4C;siSaY1ecQV{f79=62_BEVn4b3i z2%cc1n;B>De2Mev&6_LyPdz+zZK-p23(K6uToOi|A&IT z87I4c@cpy?!+Y`KV zvNAB#HZZU0evjZ^-o&v-r!VqjM0)=TCVRu=Z2EW#|T;L>1nIE7hxbBMy} p8&^&oIdeqj2>a;dwW2Lrs{RoZ+oVvr>E!N zJw5L|G>VF%;;47;h`cnK(JhMhi=wEsv~j;v6fLE!6S>ESZyH6{QlSTRI3*ea%Nx?J z>$1Y%LIesCC`6zTfkFhndebP3Z z^eTRf&DW=aJm>I6kH%sVzCfJETFT$YLpUAYZ)=kMUkKZ|0&TFNsXqE5r5_49DR(5c{DFUTX~I!TSm4 zcwaALFxsK1lOo8d~1%+hi$!s-O!q}8I{X16VA2Jr#IOih+^bQj_FE-`q$^G)Pk}e z)cJd3JGYWM9;QuUjLln;Tno>{5`;cEE|;P`vQrxh?nJ0t$#$-K+2>{N?@7VOupRqv zvM*QRHC&4=(9-1Bk4F%mbH`*N9OvwGE(M|gE7;yEyFv^0ccIQQ*v?x>!*O>`TITvP z04$&=W9TA??G)Dum-+e-TbaYpyql`pI@edm*3B@#fYes(d5)?4E+~eA(Vp z2=}lD+aDra$Nt}ioza@)y`BT-U}!7kmbp%DNIII6GYD;Z56&gmj^s68VSh)gPcl}0 za2aO6vGyG{0L{gIGwS$G>V>{I0Yl;QXOV)Snx5I`eW9~CHHOP zakw_MW-hso?uH*@ER3;zXe!2Ea@_arW4Io}a5&0vY@ct?&T(qW%oDiI}S5&CXA(Hl`HxAe-6TVA@}@4a-Bd~3ihoMp?iT*stVR2e`I4pT=Q6e1<}uWbWK?E%*w? z#JPJO@+Chv4#2+HAID=99)_{8t?c&w?q?sS!M3L&Stq&u4#%wb7V`Dk@`bn=&edb! zy`F**@ZR$!$IyFShPjx8;W!lD&v7umbMPsQPqKgR=bJmpddY3iv8{O+gF!d|Kfzes zfd}AyUxUF&BUj2b|83tGFTfNSlXCQj@xBv_;P?CN`$_gQY+J|Ya4|gB&lkq$5Ev`V zTyJvCUE6RDU4mTcj}(UMd_hJ4ZeD za?Hj`*ml0_hH~reja+Fr3QxpH+=kci37Ts63yvGh8Sp&Ee?RPw9_Zef_aS#K8$0WI zj^~DcW#`6!IeZq3K?c^JiZ*C26;okLc-^6x44+fyN%pmp`@Z`=#uB`W7x6c&M7}u@ z&RH3lv+)u};x#XFWcEMeK3!G9`Kh{+n&O5$l_9Tv6n_ zygn+a^INd(Hnh(t9`D2J#tk{QwJs-OmYdc;??LxV(HCF;cUqm;DWpOK{y!q%XXs7g z_rXnC(Phu;2|u&9HhI0?xDbA)d=QVp-wj5gKU(q>`CGvluqd=R+27Id_XD2%hTqcs zK3jv@#xlPn&BGb!jC|>44y?sF`6}cnzlbuwGrkM&)$cQV#b$qXJrANz)akYhwu{YpLLRbb6l+Fe9gC(Z^JR;_y&ww=)3vHsKhlm z4n460hQYPK^`(XiYkABy>}~k| zybR~z0{A@I&twYm_r4u(uj_R@&-!EF`^S5--Q=~yw%1*WXK@3J*)K5}K9i28v0aY) zu{}acv++2V;VXnT?axPe2G`>}42QA$9d5z|jE2WX;7Zv35+t7;+mda2Z@z0naxQkn zP8fho5ZYM7cIc0Ndk>Yk4S&KUI7b%3F|LR8&AsQ@FpeiQ^4Z=C&80R}=!!vbzB;~+ zO}K~9r)2INS&Z9p7WPCtY-ln*CHMhOLItMaKFq*4I4%ccJNS%j>|~$3&L$iCLWTAV z5!e_JSob@_H~-d^uZc6MHSvn-+IW8L$Gc8uAX`<-+I@ZW4^;`r&Qt z;Z7oTXZtY>#u*5GZ_oBH_|7~L_Qmb&K3MM-tiaRgfRJ4Oj>U^O4Kq;*`#{3XNOU+U)Nz3e3vf90GLL=*m$kS@eJ&@{q;S+6uu+p!9G3--@Qk{REF`e%y;zy z*oN`C7tRUK_1J5$>~{PJ$+S5;_S5)Hf_<0+V>T9p&;{Y$RK#|^<-MyK)u{>Oy77`PM@p??%T|1)y#Ms?|Rb;Ei80m6|1tpET3 literal 0 HcmV?d00001 diff --git a/docs/source/_static/mstile-150x150.png b/docs/source/_static/mstile-150x150.png new file mode 100644 index 0000000000000000000000000000000000000000..10e1ca526af28be1a527a1edfca82004dc3fffed GIT binary patch literal 4546 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 Czn&)m literal 0 HcmV?d00001 diff --git a/docs/source/_static/safari-pinned-tab.svg b/docs/source/_static/safari-pinned-tab.svg new file mode 100644 index 0000000..547054c --- /dev/null +++ b/docs/source/_static/safari-pinned-tab.svg @@ -0,0 +1,33 @@ + + + + +Created by potrace 1.14, written by Peter Selinger 2001-2017 + + + + + + diff --git a/docs/source/_static/site.webmanifest b/docs/source/_static/site.webmanifest new file mode 100644 index 0000000..0e0e858 --- /dev/null +++ b/docs/source/_static/site.webmanifest @@ -0,0 +1,14 @@ +{ + "name": "", + "short_name": "", + "icons": [ + { + "src": "/android-chrome-192x192.png", + "sizes": "192x192", + "type": "image/png" + } + ], + "theme_color": "#ffffff", + "background_color": "#ffffff", + "display": "standalone" +} diff --git a/docs/source/conf.py b/docs/source/conf.py index 8998530..14fba33 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,11 +1,6 @@ """Sphinx configuration file for sphinx-favicon documentation.""" -# 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 - -# -- imports and read config ------------------------------------------------- +# -- imports and read config --------------------------------------------------- import datetime as dt import pkg_resources @@ -13,36 +8,76 @@ version = pkg_resources.require("sphinx-favicon")[0].version year = dt.datetime.now().year -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - +# -- Project information ------------------------------------------------------- project = "sphinx-favicon" copyright = f"{year}, Timo Metzger" author = "Timo Metzger" release = version -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - "sphinx_rtd_theme", - "myst_parser", -] - +# -- General configuration ----------------------------------------------------- +extensions = ["sphinx_favicon", "sphinx_copybutton"] source_suffix = [".rst", ".md"] - templates_path = ["_templates"] -exclude_patterns = [] - +exclude_patterns = ["Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"] -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = "sphinx_rtd_theme" +# -- Options for HTML output --------------------------------------------------- +html_theme = "pydata_sphinx_theme" html_static_path = ["_static"] +html_css_files = ["custom.css"] html_context = { "display_github": True, "github_user": "tcmetzger", "github_repo": "sphinx-favicon", "github_version": "main/docs/source/", } + +# -- Options for the html theme ------------------------------------------------ +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/tcmetzger/sphinx-favicon", + "icon": "fa-brands fa-github", + }, + { + "name": "PyPi", + "url": "https://pypi.org/project/sphinx-favicon/", + "icon": "fa-brands fa-python", + }, + ], + "logo": {"text": project}, + "use_edit_page_button": True, + "announcement": "https://raw.githubusercontent.com/12rambau/sphinx-favicon/doc/docs/source/_static/announcment.html", +} + +# -- Option for favicons ------------------------------------------------------- + +favicons = [ + { + "rel": "apple-touch-icon", + "size": "180x180", + "static-file": "apple-touch-icon.png", + }, + { + "rel": "icon", + "type": "image/png", + "size": "32x32", + "static-file": "favicon-32x32.png", + }, + { + "rel": "icon", + "type": "image/png", + "size": "16x16", + "static-file": "favicon-16x16.png", + }, + {"rel": "manifest", "static-file": "site.webmanifest"}, + {"rel": "mask-icon", "color": "#2d89ef", "static-file": "safari-pinned-tab.svg"}, + # { + # "name": "msapplication-TileColor", + # "content": "#2d89ef", + # }, + # { + # "name": "theme-color", + # "size": "#ffffff", + # }, +] diff --git a/docs/source/index.rst b/docs/source/index.rst index 3950f3b..d85cd17 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,18 +1,261 @@ Sphinx Favicon ============== -.. toctree:: - :maxdepth: 3 - :caption: Contents: +**A Sphinx extension to add custom favicons** -.. include:: ../../README.md - :parser: myst_parser.sphinx_ - :start-line: 8 +With **sphinx-favicon**, you can add custom favicons to your Sphinx HTML documentation quickly and easily. +You can define favicons directly in your `conf.py`, with different `rel` attributes such as `"icon" `__ or `"apple-touch-icon" `__ and any favicon size. + +The **sphinx-favicon** extension gives you more flexibility than the `standard "favicon.ico" supported by Sphinx `__. It provides a quick and easy way to add the most important favicon formats for different browsers and devices. + +Installation +------------ + +Use ``pip`` to install **sphinx-favicon** in your environment: + +.. code-block:: console + + pip install sphinx-favicon + + +Usage +----- + +After installing **sphinx-favicon**, you can configure the extension directly in `conf.py`. There are two ways to include favicon files in your configuration: + +- Use an **absolute URL** for a favicon file (beginning with ``http://`` or ``https://``). If you use an absolute URL, use the ``href`` parameter. +- Use a **local static file** as a favicon. Make sure you place your local static favicon file(s) inside a directory listed in `Sphinx "html_static_path" `__. To use a relative path, use the ``static-file`` parameter. + +To configure **sphinx-favicon**, first add ``sphinx_favicon`` to the list of extensions: + +.. code-block:: python + + extensions = [ + #[...] + "sphinx_favicon", + ] + +Several options are then available to define favicons. They are listed in the following sections. + +Provide detailed metadata as a list of dicts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use a list of dicts for maximum control over the favicons added to your HTML document. You can use any parameters to define your favicon as long as they are interpreted by browsers. Some specific keywords will change the HTML content: + +- ``rel``: a value for the favicon's ``rel`` attribute, usually either the standard `icon `__ or a custom extension like `apple-touch-icon `__. +- ``sizes``: a value for the favicon's ``sizes`` attribute as defined `here `__. It is computed on the fly if not set. +- ``type``: a value specifying the favicon's MIME type as defined `here `__. It is computed automatically if not set. +- ``href``: the **absolute URL** to the favicon's image file (not required if you use the ``static-file`` parameter) +- ``static-file``: the **local static file** to use as favicon. Please note that this path should be relative to a directory listed in `Sphinx "html_static_path" `__ (usually ``_static``). If you define both ``static-file`` and ``href``, the value for ``href`` will be ignored. +- ``name``: a value for the favicon's ``name``. Usually set for microsoft app metadata. If set, the tag will be set to ``meta``. + +**Example** + +.. code-block:: python + + html_static_path = ["_static"] # html_static_path is required if you use the "static-file" parameter + + favicons = [ + { + "rel": "icon", + "static-file": "icon.svg", # => use `_static/icon.svg` + "type": "image/svg+xml", + }, + { + "rel": "icon", + "sizes": "16x16", + "href": "https://secure.example.com/favicon/favicon-16x16.png", + "type": "image/png", + }, + { + "rel": "icon", + "sizes": "32x32", + "href": "https://secure.example.com/favicon/favicon-32x32.png", + "type": "image/png", + }, + { + "rel": "apple-touch-icon", + "sizes": "180x180", + "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png", + "type": "image/png", + }, + ] + +Based on this configuration, Sphinx will include the following favicon information in the HTML `` element: + +.. code-block:: html + + + + + + +Note that the relative path to the favicon's image file in the static directory will be adjusted according to each html file's location. + +To make things easier for you, **sphinx-favicon** can also add *some* metadata to each favicon's `` element automatically: + +- If you don't provide the ``rel`` argument, **sphinx-favicon** automatically adds ``rel="icon"`` for ``link`` tags. +- if you don't provide the ``type`` argument, **sphinx-favicon** automatically determines the MIME type based on the image's filename extension. +- If not provided, **sphinx-favicon** will compute the ``sizes`` arguments automatically from the image provided in ``href``. + +Therefore, the following simplified configuration generates the exact same HTML result as above: + +.. code-block:: python + + html_static_path = ["_static"] + + favicons = [ + {"static-file": "icon.svg"}, # => use `_static/icon.svg` + {"href": "https://secure.example.com/favicon/favicon-16x16.png"}, + {"href": "https://secure.example.com/favicon/favicon-32x32.png"}, + { + "rel": "apple-touch-icon", + "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png", + }, + ] + +Provide a single dict for just one favicon +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to add just one custom favicon, you can also use a simple dict in ``conf.py``: + +.. code-block:: python + + favicons = { + "rel": "apple-touch-icon", + "sizes": "180x180", + "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png", + } + +Based on this configuration, Sphinx will include the following favicon information in the ```` of every HTML file: + +.. code-block:: html + + + +Provide a list of local favicon files or URLs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The quickest way to add favicons is to just add a list of favicon URLs to ``conf.py``. + +.. code-block:: python + + html_static_path = ["_static"] + favicons = [ + "icon.svg", # => `_static_/icon.svg` + "https://secure.example.com/favicon/favicon-16x16.gif", + "https://secure.example.com/favicon/favicon-32x32.png", + "https://secure.example.com/favicon/apple-touch-icon-180x180.png", + ] + +Based on this configuration, Sphinx will include the following favicon information in the HTML ```` element: + +.. code-block:: html + + + + + + +Please note that if your URLs don't start with ``https://``, ``http://`` or ``/``, they will be considered a static file inside a directory listed in `Sphinx "html_static_path" `__. + +Contribute +---------- + +Thank you for your help improving **sphinx-favicon**! + +**sphinx-favicon** uses `nox `__ to automate several +development-related tasks. +Currently, the project uses four automation processes (called sessions) in ``noxfile.py``: + +- ``mypy``: to perform a mypy check on the lib; +- ``test``: to run the test with pytest; +- ``docs``: to build the documentation in the ``build`` folder; +- ``lint``: to run the pre-commits in an isolated environment + +Every nox session is run in its own virtual environment, and the dependencies are +installed automatically. + +To run a specific nox automation process, use the following command: + +.. code-block:: console + + nox -s {{session name}} + +Workflow for contributing changes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We follow a typical GitHub workflow of: + +- Create a personal fork of this repo +- Create a branch +- Open a pull request +- Fix findings of various linters and checks +- Work through code review + +For each pull request, the documentation is built and deployed to make it easier to review the changes in the PR. To access this, click on the Read the Docs preview in the CI/CD jobs. + +.. note:: + + The sections below cover the steps to do this in more detail. + +Clone the repository +^^^^^^^^^^^^^^^^^^^^ + +First off, you'll need your own copy of the **sphinx-favicon** codebase. You can clone it for local development like so: + +Fork the repository so you have your own copy on GitHub. See the `GitHub forking guide for more information `__. Then, clone the repository locally so that you have a local copy to work on: + +.. code-block:: console + + git clone https://github.com/{{ YOUR USERNAME }}/sphinx-favicon + cd sphinx-favicon + +Then install the development version of the extention: + +.. code-block:: console + + pip install -e .[dev] + +This will install the sphinx-favicon library, together with two extra tools: +- `pre-commit `__ for automatically enforcing code standards and quality checks before commits. +- `nox `__, for automating common development tasks. + +Lastly, activate the pre-commit hooks by running: + +.. code-block:: console + + pre-commit install + +This will install the necessary dependencies to run pre-commit every time you make a commit with Git. + +Contribute to the codebase +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Any larger updates to the codebase should include tests and documentation. +The tests are located in the ``tests`` folder, and the documentation is located in the ``docs`` folder. + +To run the tests locally, use the following command: + +.. code-block:: console + + nox -s test + +See :ref:`below ` for more information on how to update the documentation. + +.. _contributing-docs: + +Contribute to the docs +^^^^^^^^^^^^^^^^^^^^^^ + +The documentation is built using `Sphinx `__ and +deployed to `Read the Docs `__. + +To build the documentation locally, use the following command: + +.. code-block:: console + + nox -s docs -.. Indices and tables -.. ================== -.. * :ref:`genindex` -.. * :ref:`modindex` -.. * :ref:`search` diff --git a/noxfile.py b/noxfile.py index 6083f39..eeaf51b 100644 --- a/noxfile.py +++ b/noxfile.py @@ -3,7 +3,7 @@ import nox -@nox.session(python=["3.7", "3.8", "3.9"], reuse_venv=True) +@nox.session(reuse_venv=True) def test(session): """Apply the tests on the lib.""" session.install(".[test]") @@ -23,3 +23,17 @@ def mypy(session): "--non-interactive", *test_files, ) + + +@nox.session(name="docs", reuse_venv=True) +def docs(session): + """Build the docs.""" + session.install(".[doc]") + session.run("sphinx-build", "-b=html", "docs/source", "docs/build/html") + + +@nox.session(reuse_venv=True) +def lint(session): + """Run pre-commit linting checks.""" + session.install(".[test]") + session.run("pre-commit", "run", "--all-files", external=True) diff --git a/setup.cfg b/setup.cfg index d32df74..c6dbe84 100644 --- a/setup.cfg +++ b/setup.cfg @@ -42,7 +42,8 @@ test = beautifulsoup4 dev = nox + pre-commit doc = - sphinx + sphinx<6 pydata-sphinx-theme - + sphinx-copybutton diff --git a/sphinx_favicon/__init__.py b/sphinx_favicon/__init__.py index 95b7952..2810413 100644 --- a/sphinx_favicon/__init__.py +++ b/sphinx_favicon/__init__.py @@ -74,7 +74,6 @@ def generate_meta(favicon: Dict[str, str]) -> str: # build the html element parameters = [f'{k}="{v}"' for k, v in favicon.items()] html_element = f" <{tag} {' '.join(parameters)}>" - print(html_element) return html_element