sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.6k stars 2.12k forks source link

epub builder tries to use `html_favicon` but does not know the mime type for `.ico` #10350

Open aucampia opened 2 years ago

aucampia commented 2 years ago

Describe the bug

When building epub with 4.5.0, the follow warning is produced:

WARNING: unknown mimetype for _static/RDFlib.ico, ignoring

This prevents the -W flag from being useful when building epub and having a html_favicon set.

How to Reproduce

Just the commands:

git clone git@github.com:RDFLib/rdflib.git
cd rdflib
git checkout d711a3518c033695e41a84c147bc09aca0893d21
python3.9 -m venv .venv
.venv/bin/python -m pip install '.[docs]'
.venv/bin/python -m pip freeze
(export PATH=$(readlink -f .venv)/bin:${PATH} PYTHONPATH=$(readlink -f .venv) &&
  cd docs &&
  python -m sphinx -T -E -W --keep-going -b epub -d _build/doctrees -D language=en . _build/epub)
echo $?

Commands with output

$ git clone git@github.com:RDFLib/rdflib.git
Cloning into 'rdflib'...
remote: Enumerating objects: 30581, done.
remote: Counting objects: 100% (2333/2333), done.
remote: Compressing objects: 100% (1071/1071), done.
remote: Total 30581 (delta 1519), reused 1875 (delta 1219), pack-reused 28248
Receiving objects: 100% (30581/30581), 15.88 MiB | 11.95 MiB/s, done.
Resolving deltas: 100% (19322/19322), done.
$ cd rdflib
$ git checkout d711a3518c033695e41a84c147bc09aca0893d21
Note: switching to 'd711a3518c033695e41a84c147bc09aca0893d21'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at d711a351 Merge pull request #1818 from aucampia/iwana-20220414T2246-sphinx_warnings
$ python3.9 -m venv .venv
$ .venv/bin/python -m pip install '.[docs]'
Processing /var/tmp/sphinx-epub-mime/rdflib
  DEPRECATION: A future pip version will change local packages to be built in-place without first copying to a temporary directory. We recommend you use --use-feature=in-tree-build to test your packages with this new behavior before it becomes the default.
   pip 21.3 will remove support for this functionality. You can find discussion regarding this at https://github.com/pypa/pip/issues/7555.
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
    Preparing wheel metadata ... done
Collecting pyparsing
  Using cached pyparsing-3.0.8-py3-none-any.whl (98 kB)
Collecting isodate
  Using cached isodate-0.6.1-py2.py3-none-any.whl (41 kB)
Requirement already satisfied: setuptools in ./.venv/lib/python3.9/site-packages (from rdflib==6.2.0a0) (57.4.0)
Collecting sphinxcontrib-kroki
  Using cached sphinxcontrib_kroki-1.3.0-py3-none-any.whl
Collecting sphinxcontrib-apidoc
  Using cached sphinxcontrib_apidoc-0.3.0-py2.py3-none-any.whl (8.5 kB)
Collecting sphinx<5
  Using cached Sphinx-4.5.0-py3-none-any.whl (3.1 MB)
Collecting myst-parser
  Using cached myst_parser-0.17.1-py3-none-any.whl (52 kB)
Collecting requests>=2.5.0
  Using cached requests-2.27.1-py2.py3-none-any.whl (63 kB)
Collecting imagesize
  Using cached imagesize-1.3.0-py2.py3-none-any.whl (5.2 kB)
Collecting docutils<0.18,>=0.14
  Using cached docutils-0.17.1-py2.py3-none-any.whl (575 kB)
Collecting sphinxcontrib-qthelp
  Using cached sphinxcontrib_qthelp-1.0.3-py2.py3-none-any.whl (90 kB)
Collecting Pygments>=2.0
  Using cached Pygments-2.11.2-py3-none-any.whl (1.1 MB)
Collecting babel>=1.3
  Using cached Babel-2.9.1-py2.py3-none-any.whl (8.8 MB)
Collecting importlib-metadata>=4.4
  Using cached importlib_metadata-4.11.3-py3-none-any.whl (18 kB)
Collecting sphinxcontrib-jsmath
  Using cached sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl (5.1 kB)
Collecting packaging
  Using cached packaging-21.3-py3-none-any.whl (40 kB)
Collecting sphinxcontrib-serializinghtml>=1.1.5
  Using cached sphinxcontrib_serializinghtml-1.1.5-py2.py3-none-any.whl (94 kB)
Collecting sphinxcontrib-applehelp
  Using cached sphinxcontrib_applehelp-1.0.2-py2.py3-none-any.whl (121 kB)
Collecting snowballstemmer>=1.1
  Using cached snowballstemmer-2.2.0-py2.py3-none-any.whl (93 kB)
Collecting Jinja2>=2.3
  Using cached Jinja2-3.1.1-py3-none-any.whl (132 kB)
Collecting sphinxcontrib-devhelp
  Using cached sphinxcontrib_devhelp-1.0.2-py2.py3-none-any.whl (84 kB)
Collecting alabaster<0.8,>=0.7
  Using cached alabaster-0.7.12-py2.py3-none-any.whl (14 kB)
Collecting sphinxcontrib-htmlhelp>=2.0.0
  Using cached sphinxcontrib_htmlhelp-2.0.0-py2.py3-none-any.whl (100 kB)
Collecting pytz>=2015.7
  Using cached pytz-2022.1-py2.py3-none-any.whl (503 kB)
Collecting zipp>=0.5
  Using cached zipp-3.8.0-py3-none-any.whl (5.4 kB)
Collecting MarkupSafe>=2.0
  Using cached MarkupSafe-2.1.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (25 kB)
Collecting idna<4,>=2.5
  Using cached idna-3.3-py3-none-any.whl (61 kB)
Collecting certifi>=2017.4.17
  Using cached certifi-2021.10.8-py2.py3-none-any.whl (149 kB)
Collecting urllib3<1.27,>=1.21.1
  Using cached urllib3-1.26.9-py2.py3-none-any.whl (138 kB)
Collecting charset-normalizer~=2.0.0
  Using cached charset_normalizer-2.0.12-py3-none-any.whl (39 kB)
Collecting six
  Using cached six-1.16.0-py2.py3-none-any.whl (11 kB)
Collecting attrs>=19
  Using cached attrs-21.4.0-py2.py3-none-any.whl (60 kB)
Collecting mdit-py-plugins~=0.3.0
  Using cached mdit_py_plugins-0.3.0-py3-none-any.whl (43 kB)
Collecting pyyaml
  Using cached PyYAML-6.0-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (661 kB)
Collecting typing-extensions
  Using cached typing_extensions-4.1.1-py3-none-any.whl (26 kB)
Collecting markdown-it-py<3.0.0,>=1.0.0
  Using cached markdown_it_py-2.0.1-py3-none-any.whl (84 kB)
Collecting mdurl~=0.1
  Using cached mdurl-0.1.1-py3-none-any.whl (10 kB)
Collecting pbr
  Using cached pbr-5.8.1-py2.py3-none-any.whl (113 kB)
Building wheels for collected packages: rdflib
  Building wheel for rdflib (PEP 517) ... done
  Created wheel for rdflib: filename=rdflib-6.2.0a0-py3-none-any.whl size=490952 sha256=3ea5bf3c5489915f618793610b34b7258a5a92f604fdd625f8da6fa9ce04b187
  Stored in directory: /tmp/pip-ephem-wheel-cache-11_vbro8/wheels/16/7f/e8/d4fd7dcf411570999c1cd5f754aee633ef8a865ae93f4e20bd
Successfully built rdflib
Installing collected packages: zipp, urllib3, pytz, pyparsing, mdurl, MarkupSafe, idna, charset-normalizer, certifi, attrs, sphinxcontrib-serializinghtml, sphinxcontrib-qthelp, sphinxcontrib-jsmath, sphinxcontrib-htmlhelp, sphinxcontrib-devhelp, sphinxcontrib-applehelp, snowballstemmer, six, requests, Pygments, packaging, markdown-it-py, Jinja2, importlib-metadata, imagesize, docutils, babel, alabaster, typing-extensions, sphinx, pyyaml, pbr, mdit-py-plugins, isodate, sphinxcontrib-kroki, sphinxcontrib-apidoc, rdflib, myst-parser
Successfully installed Jinja2-3.1.1 MarkupSafe-2.1.1 Pygments-2.11.2 alabaster-0.7.12 attrs-21.4.0 babel-2.9.1 certifi-2021.10.8 charset-normalizer-2.0.12 docutils-0.17.1 idna-3.3 imagesize-1.3.0 importlib-metadata-4.11.3 isodate-0.6.1 markdown-it-py-2.0.1 mdit-py-plugins-0.3.0 mdurl-0.1.1 myst-parser-0.17.1 packaging-21.3 pbr-5.8.1 pyparsing-3.0.8 pytz-2022.1 pyyaml-6.0 rdflib-6.2.0a0 requests-2.27.1 six-1.16.0 snowballstemmer-2.2.0 sphinx-4.5.0 sphinxcontrib-apidoc-0.3.0 sphinxcontrib-applehelp-1.0.2 sphinxcontrib-devhelp-1.0.2 sphinxcontrib-htmlhelp-2.0.0 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-kroki-1.3.0 sphinxcontrib-qthelp-1.0.3 sphinxcontrib-serializinghtml-1.1.5 typing-extensions-4.1.1 urllib3-1.26.9 zipp-3.8.0
WARNING: You are using pip version 21.2.3; however, version 22.0.4 is available.
You should consider upgrading via the '/var/tmp/sphinx-epub-mime/rdflib/.venv/bin/python -m pip install --upgrade pip' command.
$ .venv/bin/python -m pip freeze
alabaster==0.7.12
attrs==21.4.0
Babel==2.9.1
certifi==2021.10.8
charset-normalizer==2.0.12
docutils==0.17.1
idna==3.3
imagesize==1.3.0
importlib-metadata==4.11.3
isodate==0.6.1
Jinja2==3.1.1
markdown-it-py==2.0.1
MarkupSafe==2.1.1
mdit-py-plugins==0.3.0
mdurl==0.1.1
myst-parser==0.17.1
packaging==21.3
pbr==5.8.1
Pygments==2.11.2
pyparsing==3.0.8
pytz==2022.1
PyYAML==6.0
rdflib @ file:///var/tmp/sphinx-epub-mime/rdflib
requests==2.27.1
six==1.16.0
snowballstemmer==2.2.0
Sphinx==4.5.0
sphinxcontrib-apidoc==0.3.0
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-kroki==1.3.0
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5
typing_extensions==4.1.1
urllib3==1.26.9
zipp==3.8.0
$ (export PATH=$(readlink -f .venv)/bin:${PATH} PYTHONPATH=$(readlink -f .venv) &&
>   cd docs &&
>   python -m sphinx -T -E -W --keep-going -b epub -d _build/doctrees -D language=en . _build/epub)
Running Sphinx v4.5.0
loading translations [en]... done
making output directory... done
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.extras.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.namespace.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.plugins.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.plugins.parsers.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.plugins.serializers.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.plugins.shared.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.plugins.shared.jsonld.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.plugins.sparql.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.plugins.sparql.results.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.plugins.stores.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/rdflib.tools.rst.
Creating file /var/tmp/sphinx-epub-mime/rdflib/docs/apidocs/modules.rst.
loading intersphinx inventory from https://docs.python.org/3.7/objects.inv...
myst v0.17.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=[], linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', disable_syntax=[], all_links_external=False, url_schemes=['http', 'https', 'mailto', 'ftp'], ref_domains=None, highlight_code_blocks=True, number_code_blocks=[], title_to_header=False, heading_anchors=None, heading_slug_func=None, html_meta=[], footnote_transition=True, substitutions=[], sub_delimiters=['{', '}'], words_per_minute=200)
building [mo]: targets for 0 po files that are out of date
building [epub]: targets for 24 source files that are out of date
updating environment: [new config] 37 added, 0 changed, 0 removed
/usr/lib64/python3.9/inspect.py:2295: UserWarning: Code: _partialmethod is not defined in namespace BRICK                                                                    
  partialmethod = obj._partialmethod
/usr/lib64/python3.9/inspect.py:2295: UserWarning: Code: _partialmethod is not defined in namespace DCAT
  partialmethod = obj._partialmethod
/usr/lib64/python3.9/inspect.py:2295: UserWarning: Code: _partialmethod is not defined in namespace PROF
  partialmethod = obj._partialmethod
/usr/lib64/python3.9/inspect.py:2295: UserWarning: Code: _partialmethod is not defined in namespace SDO
  partialmethod = obj._partialmethod
/usr/lib64/python3.9/inspect.py:2295: UserWarning: Code: _partialmethod is not defined in namespace SOSA
  partialmethod = obj._partialmethod
/usr/lib64/python3.9/inspect.py:2295: UserWarning: Code: _partialmethod is not defined in namespace SSN
  partialmethod = obj._partialmethod
/usr/lib64/python3.9/inspect.py:2295: UserWarning: Code: _partialmethod is not defined in namespace TIME
  partialmethod = obj._partialmethod
/usr/lib64/python3.9/inspect.py:2295: UserWarning: Code: _partialmethod is not defined in namespace XSD
  partialmethod = obj._partialmethod
reading sources... [100%] utilities                                                                                                                                          
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] utilities                                                                                                                                           
generating indices... genindex py-modindex done
writing additional pages... done
copying images... [100%] _static/datatype_hierarchy.png                                                                                                                      
copying static files... done
copying extra files... done
writing mimetype file...
writing META-INF/container.xml file...
writing content.opf file...
WARNING: unknown mimetype for _static/RDFlib.ico, ignoring
writing nav.xhtml file...
writing toc.ncx file...
writing rdflib.epub file...
build finished with problems, 1 warning.
$ echo $?
1

Expected behavior

I would expect the epub builder to either know how to handle .ico files or ignore html_favicon.

Your project

https://github.com/RDFLib/rdflib/tree/d711a3518c033695e41a84c147bc09aca0893d21

Screenshots

No response

OS

Linux - Fedora 35

Python version

Python 3.9.12

Sphinx version

4.5.0

Sphinx extensions

sphinxcontrib.apidoc, sphinx.ext.autodoc, sphinx.ext.doctest, sphinx.ext.intersphinx, sphinx.ext.todo, sphinx.ext.coverage, sphinx.ext.ifconfig, sphinx.ext.viewcode, myst_parser, sphinxcontrib.kroki

Extra tools

No response

Additional context

I noticed this on our RTD build after enabling sphinx.fail_on_warning. See https://readthedocs.org/projects/rdflib/builds/16660933/.

ReenigneArcher commented 1 year ago

Any workaround to this, besides disabling warnings or epub builds?

ReenigneArcher commented 1 year ago

I found a solution on readthedocs.

# disable epub mimetype warnings
suppress_warnings = ["epub.unknown_project_files"]

https://github.com/readthedocs/readthedocs.org/blob/eadf6ac6dc6abc760a91e1cb147cc3c5f37d1ea8/docs/conf.py#L235-L236

Added here: https://github.com/sphinx-doc/sphinx/commit/6d900c34f12db0d21c581c58a5dd38ab49c8ea35