Skip to content

Commit 329ff73

Browse files
brianckeeganbrianckeegan
authored
Merge pull request #3 from brianckeegan/documentation
Add documentation branch
2 parents 6b6e067 + 80904a1 commit 329ff73

17 files changed

Lines changed: 1262 additions & 163 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,4 @@ htmlcov/
1515
.venv/
1616
venv/
1717
env/
18+
docs/_build/

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,20 @@ results = reg.search("dog")
8787
all_templates = reg.list_all()
8888
```
8989

90+
## Documentation
91+
92+
Full documentation including a tutorial, user guide, and API reference is
93+
available at [memeplotlib.readthedocs.io](https://memeplotlib.readthedocs.io).
94+
95+
To build the docs locally:
96+
97+
```bash
98+
pip install -e ".[docs]"
99+
cd docs
100+
make html
101+
open _build/html/index.html
102+
```
103+
90104
## How It Works
91105

92106
1. Templates are fetched from the [memegen API](https://api.memegen.link) (blank background images + metadata)

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without a target is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/api.rst‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
API Reference
2+
=============
3+
4+
.. currentmodule:: memeplotlib
5+
6+
Top-level Functions
7+
--------------------
8+
9+
.. autofunction:: meme
10+
11+
.. autofunction:: memify
12+
13+
Meme Class
14+
-----------
15+
16+
.. autoclass:: Meme
17+
:members:
18+
:undoc-members:
19+
:show-inheritance:
20+
21+
Configuration
22+
--------------
23+
24+
.. autodata:: config
25+
:annotation: = MemeplotlibConfig()
26+
27+
.. autoclass:: memeplotlib._config.MemeplotlibConfig
28+
:members:
29+
:show-inheritance:
30+
:no-index:
31+
32+
Templates
33+
----------
34+
35+
.. autoclass:: Template
36+
:members:
37+
:show-inheritance:
38+
:exclude-members: id, name, image_url, text_positions, keywords, example
39+
40+
.. autoclass:: memeplotlib._template.TextPosition
41+
:members:
42+
:show-inheritance:
43+
:no-index:
44+
45+
.. autoclass:: TemplateRegistry
46+
:members:
47+
:undoc-members:
48+
:show-inheritance:
49+
50+
.. autoexception:: memeplotlib._template.TemplateNotFoundError
51+
:show-inheritance:
52+
53+
Rendering
54+
----------
55+
56+
.. automodule:: memeplotlib._rendering
57+
:members:
58+
:undoc-members:
59+
:show-inheritance:
60+
61+
Text Utilities
62+
---------------
63+
64+
.. automodule:: memeplotlib._text
65+
:members:
66+
:undoc-members:
67+
:show-inheritance:
68+
69+
Caching
70+
--------
71+
72+
.. automodule:: memeplotlib._cache
73+
:members:
74+
:undoc-members:
75+
:show-inheritance:

‎docs/conf.py‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
import os
7+
import sys
8+
9+
# Make sure the source directory is importable for autodoc
10+
sys.path.insert(0, os.path.abspath("../src"))
11+
12+
# -- Project information -----------------------------------------------------
13+
14+
project = "memeplotlib"
15+
copyright = "2025, Brian Keegan"
16+
author = "Brian Keegan"
17+
release = "0.1.0"
18+
19+
# -- General configuration ---------------------------------------------------
20+
21+
extensions = [
22+
"sphinx.ext.autodoc",
23+
"sphinx.ext.napoleon",
24+
"sphinx.ext.intersphinx",
25+
"sphinx.ext.viewcode",
26+
]
27+
28+
# Napoleon settings for NumPy-style docstrings
29+
napoleon_google_docstring = False
30+
napoleon_numpy_docstring = True
31+
napoleon_include_init_with_doc = True
32+
napoleon_include_private_with_doc = False
33+
napoleon_include_special_with_doc = True
34+
napoleon_use_admonition_for_examples = False
35+
napoleon_use_admonition_for_notes = True
36+
napoleon_use_ivar = False
37+
napoleon_use_param = True
38+
napoleon_use_rtype = True
39+
napoleon_attr_annotations = True
40+
41+
# Autodoc settings
42+
autodoc_member_order = "bysource"
43+
autodoc_typehints = "description"
44+
autodoc_default_options = {
45+
"members": True,
46+
"undoc-members": True,
47+
"show-inheritance": True,
48+
}
49+
50+
# Intersphinx links to external projects
51+
intersphinx_mapping = {
52+
"python": ("https://docs.python.org/3", None),
53+
"matplotlib": ("https://matplotlib.org/stable/", None),
54+
"numpy": ("https://numpy.org/doc/stable/", None),
55+
"PIL": ("https://pillow.readthedocs.io/en/stable/", None),
56+
}
57+
58+
templates_path = ["_templates"]
59+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
60+
61+
# -- Options for HTML output -------------------------------------------------
62+
63+
html_theme = "alabaster"
64+
html_theme_options = {
65+
"description": "Memes with Python's matplotlib",
66+
"github_user": "brianckeegan",
67+
"github_repo": "memeplotlib",
68+
"github_banner": True,
69+
"fixed_sidebar": True,
70+
}
71+
html_static_path = ["_static"]

‎docs/index.rst‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
memeplotlib
2+
===========
3+
4+
**Memes with Python's matplotlib.**
5+
6+
Create image macro memes using matplotlib for rendering and the
7+
`memegen <https://github.com/jacebrowning/memegen>`_ API for template discovery.
8+
9+
.. code-block:: python
10+
11+
import memeplotlib as memes
12+
13+
memes.meme("buzz", "memes", "memes everywhere")
14+
15+
Getting Started
16+
---------------
17+
18+
Install from PyPI:
19+
20+
.. code-block:: bash
21+
22+
pip install memeplotlib
23+
24+
Then head to the :doc:`tutorial` for a hands-on introduction.
25+
26+
Contents
27+
--------
28+
29+
.. toctree::
30+
:maxdepth: 2
31+
:caption: Contents
32+
33+
tutorial
34+
user_guide
35+
api
36+
37+
Indices and tables
38+
==================
39+
40+
* :ref:`genindex`
41+
* :ref:`modindex`
42+
* :ref:`search`

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/tutorial.rst‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
Getting Started
2+
===============
3+
4+
This tutorial walks you through installing memeplotlib and creating your
5+
first memes.
6+
7+
Installation
8+
------------
9+
10+
Install memeplotlib from PyPI:
11+
12+
.. code-block:: bash
13+
14+
pip install memeplotlib
15+
16+
To build the documentation locally, also install Sphinx and its dependencies:
17+
18+
.. code-block:: bash
19+
20+
pip install memeplotlib[docs]
21+
22+
Your First Meme
23+
----------------
24+
25+
The simplest way to create a meme is with the :func:`~memeplotlib.meme`
26+
function:
27+
28+
.. code-block:: python
29+
30+
import memeplotlib as memes
31+
32+
memes.meme("buzz", "memes", "memes everywhere")
33+
34+
This fetches the "Buzz Lightyear" template from the `memegen API
35+
<https://api.memegen.link>`_, renders "MEMES" at the top and
36+
"MEMES EVERYWHERE" at the bottom, and displays the result with
37+
``matplotlib.pyplot.show()``.
38+
39+
The first positional argument is the template identifier, and subsequent
40+
positional arguments are text lines placed at the template's text positions
41+
(typically top and bottom).
42+
43+
Saving to a File
44+
-----------------
45+
46+
Pass ``savefig`` to write the meme to disk. Set ``show=False`` if you do not
47+
want an interactive window:
48+
49+
.. code-block:: python
50+
51+
memes.meme("doge", "such code", "very bug",
52+
savefig="meme.png", show=False)
53+
54+
The output file format is determined by the file extension (PNG, JPEG, PDF,
55+
SVG, etc.), following matplotlib's conventions.
56+
57+
Customizing Text
58+
-----------------
59+
60+
Control font, color, and style:
61+
62+
.. code-block:: python
63+
64+
memes.meme("drake", "writing tests", "shipping to prod",
65+
font="impact", color="yellow", style="upper")
66+
67+
Available ``style`` values:
68+
69+
- ``"upper"`` (default) -- converts text to UPPERCASE.
70+
- ``"lower"`` -- converts text to lowercase.
71+
- ``"none"`` -- preserves original casing.
72+
73+
Available ``font`` shortcuts: ``"impact"``, ``"arial"``, ``"comic"``,
74+
``"times"``, ``"courier"``. You can also pass any font family name installed
75+
on your system.
76+
77+
Controlling Outline
78+
~~~~~~~~~~~~~~~~~~~~
79+
80+
The classic meme look uses white text with a black outline. You can customize
81+
both:
82+
83+
.. code-block:: python
84+
85+
memes.meme("buzz", "white on black", "the classic",
86+
color="white", outline_color="black", outline_width=3.0,
87+
show=False)
88+
89+
Using Local Images
90+
-------------------
91+
92+
You can pass a file path instead of a memegen template ID:
93+
94+
.. code-block:: python
95+
96+
memes.meme("/path/to/image.jpg", "top text", "bottom text")
97+
98+
HTTP/HTTPS URLs also work:
99+
100+
.. code-block:: python
101+
102+
memes.meme("https://example.com/image.png", "hello", "world")
103+
104+
Getting the Figure Back
105+
------------------------
106+
107+
:func:`~memeplotlib.meme` returns a ``(Figure, Axes)`` tuple, so you can
108+
continue to modify the plot before saving or showing:
109+
110+
.. code-block:: python
111+
112+
fig, ax = memes.meme("buzz", "memes", "memes everywhere", show=False)
113+
fig.savefig("custom_meme.png", dpi=300)
114+
115+
Next Steps
116+
----------
117+
118+
- See the :doc:`user_guide` for the object-oriented API, memify workflow,
119+
global configuration, and template discovery.
120+
- See the :doc:`api` for the complete API reference.

0 commit comments

Comments
 (0)