diff --git a/README.rst b/README.rst index 7c3822159..d0d4c41c8 100644 --- a/README.rst +++ b/README.rst @@ -1,13 +1,11 @@ .. This file is part of feedparser. - Copyright 2010-2025 Kurt McKee + Copyright 2010-2026 Kurt McKee Copyright 2002-2008 Mark Pilgrim Released under the BSD 2-clause license. -feedparser -########## - -Parse Atom and RSS feeds in Python. +.. image:: https://raw.githubusercontent.com/kurtmckee/feedparser/ad8e98ea352cc71cb159b55b976e31a1b041a6c8/docs/_static/banner.png + :alt: feedparser: Parse RSS/Atom/JSON feeds in Python. ---- diff --git a/assets/banner.svg b/assets/banner.svg new file mode 100644 index 000000000..c608ac5c7 --- /dev/null +++ b/assets/banner.svg @@ -0,0 +1,288 @@ + + + +feedparserParse RSS / Atom / JSON feeds in Python diff --git a/assets/logo.svg b/assets/logo.svg new file mode 100644 index 000000000..d3c0413ab --- /dev/null +++ b/assets/logo.svg @@ -0,0 +1,261 @@ + + + + diff --git a/assets/openmoji-1F4F0-newspaper-2024.svg b/assets/openmoji-1F4F0-newspaper-2024.svg new file mode 100644 index 000000000..b86e3de43 --- /dev/null +++ b/assets/openmoji-1F4F0-newspaper-2024.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/openmoji-2699-gear-2024.svg b/assets/openmoji-2699-gear-2024.svg new file mode 100644 index 000000000..20a39204f --- /dev/null +++ b/assets/openmoji-2699-gear-2024.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/assets/openmoji-E381-web-syndication-2024.svg b/assets/openmoji-E381-web-syndication-2024.svg new file mode 100644 index 000000000..2fd8aa44f --- /dev/null +++ b/assets/openmoji-E381-web-syndication-2024.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/changelog.d/20260725_110223_kurtmckee_add_logo.rst b/changelog.d/20260725_110223_kurtmckee_add_logo.rst new file mode 100644 index 000000000..6473e40d7 --- /dev/null +++ b/changelog.d/20260725_110223_kurtmckee_add_logo.rst @@ -0,0 +1,4 @@ +Documentation +------------- + +* Add a logo and banner to the project. diff --git a/docs/_static/banner.png b/docs/_static/banner.png new file mode 100644 index 000000000..c84d8f033 Binary files /dev/null and b/docs/_static/banner.png differ diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 000000000..5c314e0fe --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,23 @@ +.pre, .pre * { + font-style: normal; + font-family: monospace; + white-space: pre; +} + +/* + * The CSS code to visually hide elements comes from: + * https://www.a11yproject.com/posts/how-to-hide-content/ + * + * The CSS selector for the Sphinx/Alabaster theme comes from: + * https://github.com/pallets/pallets-sphinx-themes/blob/1512b53b/src/pallets_sphinx_themes/themes/pocoo/static/pocoo.css#L486-L498 + */ + +.visually-hidden > h1:first-child { + clip: rect(0 0 0 0); + clip-path: inset(50%); + height: 1px; + overflow: hidden; + position: absolute; + white-space: nowrap; + width: 1px; +} diff --git a/docs/_static/feedparser.css b/docs/_static/feedparser.css deleted file mode 100644 index aa1b70550..000000000 --- a/docs/_static/feedparser.css +++ /dev/null @@ -1,5 +0,0 @@ -.pre, .pre * { - font-style: normal; - font-family: monospace; - white-space: pre; -} diff --git a/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 000000000..04beb2a4a Binary files /dev/null and b/docs/_static/logo.png differ diff --git a/docs/_templates/about-no-logo.html.jinja b/docs/_templates/about-no-logo.html.jinja new file mode 100644 index 000000000..4e18440f8 --- /dev/null +++ b/docs/_templates/about-no-logo.html.jinja @@ -0,0 +1,23 @@ +{% if theme_logo %} +

{{ project }}

+ {% elif theme_logo_name|lower != 'false' %} +

{{ theme_logo_name }}

+ {% endif %} +
+

+{% else %} +

{{ project }}

+{% endif %} + +{% if theme_description %} +

{{ theme_description }}

+{% endif %} + +{% if theme_github_user and theme_github_repo %} +

+ Source code repository +

+{% endif %} diff --git a/docs/_templates/about.html.jinja b/docs/_templates/about.html.jinja new file mode 100644 index 000000000..4c0118b72 --- /dev/null +++ b/docs/_templates/about.html.jinja @@ -0,0 +1,24 @@ +{% if theme_logo %} +

{{ project }}

+ {% elif theme_logo_name|lower != 'false' %} +

{{ theme_logo_name }}

+ {% endif %} +
+

+{% else %} +

{{ project }}

+{% endif %} + +{% if theme_description %} +

{{ theme_description }}

+{% endif %} + +{% if theme_github_user and theme_github_repo %} +

+ Source code repository +

+{% endif %} diff --git a/docs/colophon.rst b/docs/colophon.rst new file mode 100644 index 000000000..cbd08528d --- /dev/null +++ b/docs/colophon.rst @@ -0,0 +1,36 @@ +Colophon +######## + +The feedparser logo and banner build on others' work. + +* The newspaper in the logo is `Emoji 1F4F0`_, + the gear in the logo is `Emoji 2699`_, + and the web syndication icon in the logo is `Emoji E381`_. + They were designed by `OpenMoji`_, the open-source emoji and icon project. + + License: `CC BY-SA 4.0`_ + +* The text in the banner uses the `Noto Sans`_ font, + designed by the `Noto Project`_. + + License: `SIL Open Font License, version 1.1 `_ + +* The images and text were pieced together using `Inkscape`_. + + License: `GNU GPL, version 2`_ + + + +.. Links +.. ----- +.. +.. _Emoji 1F4F0: https://openmoji.org/library/emoji-1F4F0/ +.. _Emoji 2699: https://openmoji.org/library/emoji-2699/ +.. _Emoji E381: https://openmoji.org/library/emoji-E381/ +.. _OpenMoji: https://openmoji.org/ +.. _CC BY-SA 4.0: https://creativecommons.org/licenses/by-sa/4.0/ +.. _Noto Sans: https://fonts.google.com/noto/specimen/Noto+Sans +.. _Noto Project: https://github.com/notofonts/latin-greek-cyrillic +.. _Noto Sans License: https://github.com/notofonts/latin-greek-cyrillic/blob/4bc63d7ebca1faed49c6c685f380ba0abc2c1941/OFL.txt +.. _Inkscape: https://inkscape.org/ +.. _GNU GPL, version 2: https://inkscape.org/about/license/ diff --git a/docs/conf.py b/docs/conf.py index 6bcf1784a..bed8f8fac 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,7 +9,7 @@ # Project information project = "feedparser" -copyright = "2010-2025 Kurt McKee, 2004-2008 Mark Pilgrim" +copyright = "2010-2026 Kurt McKee, 2004-2008 Mark Pilgrim" language = "en" # General configuration @@ -19,13 +19,46 @@ # HTML options # Files in `html_static_path` will be copied to `_static/` when compiled. -html_static_path = ["_static"] -html_theme = "sphinx_rtd_theme" -# Example feeds that will be hosted by Read the Docs. -# The files are double-nested in 'examples/examples/' -# because they're copied to the root of the drive. +html_theme = "alabaster" +html_static_path = [ + "_static", +] +html_theme_options = { + "logo": "logo.png", + "logo_name": True, + "description": "Parse RSS/Atom/JSON feeds in Python.", + # Link to GitHub + "github_user": "kurtmckee", + "github_repo": "feedparser", + "github_button": True, + "github_type": "star", + "github_count": False, + # Don't show "Powered by" text. + "show_powered_by": False, +} +templates_path = ["_templates"] +html_sidebars = { + "index": [ + "about-no-logo.html.jinja", # Custom + "donate.html", + "navigation.html", + "relations.html", + "searchbox.html", + ], + "**": [ + "about.html.jinja", # Custom + "searchfield.html", + "navigation.html", + "relations.html", + "donate.html", + ], +} html_extra_path = ["examples"] + +# Don't copy source .rst files into the built documentation. +html_copy_source = False + sys.path.append(str(pathlib.Path(__file__).parent / "extensions")) extensions = [ # Make Sphinx add a to `feedparser.css`. diff --git a/docs/index.rst b/docs/index.rst index 6bbc46cdf..40aa02c19 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,11 @@ -============= -Documentation -============= +.. rst-class:: visually-hidden + +feedparser - Parse RSS/Atom/JSON feeds in Python +################################################ + +.. image:: _static/banner.png + :alt: feedparser - Parse RSS/Atom/JSON feeds in Python + This documentation claims to describe the behavior of :program:`feedparser` |version|. It does not claim to describe the behavior of any other version. @@ -19,6 +24,11 @@ implied warranties. See :ref:`the documentation license ` for more det advanced http annotated-examples - changelog reference + +.. toctree:: + :maxdepth: 1 + + changelog license + colophon