diff --git a/.gitignore b/.gitignore index 0322ffb..a4b5d1a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ __pycache__/ +cache/ output/ venv/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d30be0c..d9690ed 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,4 +1,4 @@ -# pre-commit run --all-files +# To execute those rules on all files: pre-commit run --all-files repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.4.0 @@ -10,35 +10,8 @@ repos: - id: check-yaml - id: debug-statements - id: end-of-file-fixer - exclude: "resources/.*|docs/make.bat" - id: trailing-whitespace - id: mixed-line-ending args: ['--fix=lf'] - exclude: "docs/make.bat" - id: check-added-large-files args: ['--maxkb=1000'] -# - repo: https://github.com/pre-commit/mirrors-mypy -# rev: v0.942 -# hooks: -# - id: mypy -- repo: https://github.com/psf/black - rev: 23.1.0 - hooks: - - id: black - args: [--target-version, py36] -- repo: https://github.com/asottile/blacken-docs - rev: 1.13.0 - hooks: - - id: blacken-docs - additional_dependencies: [black==22.1.0] - exclude: "docs/user/robustness.md" -- repo: https://github.com/charliermarsh/ruff-pre-commit - rev: 'v0.0.259' - hooks: - - id: ruff - args: ['--fix'] -- repo: https://github.com/asottile/pyupgrade - rev: v3.3.1 - hooks: - - id: pyupgrade - args: [--py39-plus] diff --git a/README.md b/README.md index 797cba6..ba210b7 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,21 @@ Website py-pdf ## Install requirements - ``` $ pip install -r requirements.txt $ pre-commit install ``` -## Publish +## Launch local server with livereload +``` +$ invoke livereload +``` + +## Adding a Python dependency +1. Edit `requirements.in` +2. Run `pip-compile requirements.in` to generate `requirements.txt` +## Publish ``` $ make github ``` diff --git a/content/about-py-pdf-org.md b/content/about-py-pdf-org.md deleted file mode 100644 index e8c4775..0000000 --- a/content/about-py-pdf-org.md +++ /dev/null @@ -1,13 +0,0 @@ -Title: The py-pdf organization -Date: 2023-03-28 10:20 -Modified: 2023-03-28 10:20 -Category: py-pdf -Tags: Governance -Slug: py-pdf-organization -Authors: Martin Thoma -Summary: What py-pdf is about - -The py-pdf organization is a loose group of Python developers who provide -libraries and applications around PDF documents. - -You can see the full list of our projects [on GitHub](https://github.com/py-pdf). diff --git a/content/images/.gitkeep b/content/images/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/content/images/github-org-public-membership.png b/content/images/github-org-public-membership.png new file mode 100644 index 0000000..1ca257e Binary files /dev/null and b/content/images/github-org-public-membership.png differ diff --git a/content/images/pypdf-snake.png b/content/images/pypdf-snake.png new file mode 100644 index 0000000..8c7f6c2 Binary files /dev/null and b/content/images/pypdf-snake.png differ diff --git a/content/pages/index.md b/content/pages/index.md new file mode 100644 index 0000000..f5d8b14 --- /dev/null +++ b/content/pages/index.md @@ -0,0 +1,10 @@ +Title: The py-pdf organization +Slug: ../index +Save_as: index.html +Authors: Martin Thoma +Summary: What py-pdf is about + +The py-pdf organization is a group of Python developers who provide +libraries and applications around PDF documents. + +
![pypdf logo](images/pypdf-snake.png)
diff --git a/content/pages/maintainer-guidelines.md b/content/pages/maintainer-guidelines.md new file mode 100644 index 0000000..3b2c2e3 --- /dev/null +++ b/content/pages/maintainer-guidelines.md @@ -0,0 +1,97 @@ +Title: Maintainer guidelines +Tags: guideline, maintainer + +## Table of contents + + + + +- [Volunteering](#volunteering) +- [Governance](#governance) + * [The relationship of py-pdf to its projects](#the-relationship-of-py-pdf-to-its-projects) + * [Conditions for projects to be added to py-pdf](#conditions-for-projects-to-be-added-to-py-pdf) + * [Responsibility of project maintainers](#responsibility-of-project-maintainers) + * [GitHub roles](#github-roles) +- [Releases](#releases) + + + +## Volunteering +All [@py-pdf](https://github.com/py-pdf) members are volunteers. +They dedicate some of their time to maintain open-source projects, answer questions and review Pull Requests. + +[@py-pdf](https://github.com/py-pdf) members should never be required to operate within deadlines, or even respond within a given time frame. + +If you are a user of a [@py-pdf](https://github.com/py-pdf) project and want something done, +whether it is a bugfix or a feature request, your best options for achieving what you want are: + +* being polite and patient +* volunteer to contribute yourself + +To all [@py-pdf](https://github.com/py-pdf) members, remember: [it's okay to hit pause](https://opensource.guide/best-practices/#its-okay-to-hit-pause), and take time away from volunteer open-source work. + +
+ +## Governance +`py-pdf` governance model is descibed there: + + +
+ +## The relationship of py-pdf to its projects + +`py-pdf` wants to ensure the Python-PDF ecosystem is prospering. We recognize that individual +maintainers did and still do an outstanding job, but we also see that personal lives sometimes +move away from software projects. + +That means: + +1. `py-pdf` offers the platform to exchange ideas and provide feedback +2. `py-pdf` administrators who are not project members do interfere, when (a) no activity by the maintainers is in the project for at least 6 months and at least 3 friendly "are you alive" questions over at least 6 weeks. (b) security issues are detected +3. `py-pdf` leaves the projects do their thing in all other cases. + +
+ +## Conditions for projects to be added to py-pdf + +We want projects which provide value to users and we need to be able to maintain them. We want to improve the Python / PDF ecosystem and not scatter it. + +1. The project has to be a Python project and about PDF documents +2. If it's a software project, it has (1) a README with the projects purpose, installation instructions, and a usage example (2) it's either the main project or the fork that has more popularity measured in GitHub stars +3. It either has a different purpose than all other projects in `py-pdf` or is more popular than the existing projects for that purpose +4. It needs to be a FOSS license (e.g. BSD, MIT, Apache) + +
+ +## Responsibility of project maintainers + +1. **Software Reliability**: Please ensure that your project follows best practices in software development. Introduce a [deprecation process](https://pypdf.readthedocs.io/en/latest/dev/deprecations.html) and follow it. +2. **Kindness**: We are all here because it's fun to help others and create good software. But we are humans: people can have bad days and people might not speak English as a mother tongue. When in doubt, assume the best. Let people know how you perceived their interaction. +3. **Know your Limits**: It's ok to reduce the time you spend on your project or even step away from it. Stay healthy. +4. **Let your Project Grow**: Especially if you step away, let others take over. Make it explicit that you're looking for another person who would take over. +It's OK to [say no](https://opensource.guide/best-practices/#learning-to-say-no). + + + +
+ +## GitHub roles +The base permission for [@py-pdf](https://github.com/py-pdf) members is set to **Write**, +meaning any [@py-pdf](https://github.com/py-pdf) member has read permissions, +can manage issues and pull requests, and also push to repositories. + +We encourage [@py-pdf](https://github.com/py-pdf) members, and especially maintainers, to make their organization membership **public** +on , in order to clarify who has ownership of the organization, and the associated rights to perform package releases: + +![](../images/github-org-public-membership.png) + +
+ +## Releases +Depending on the projects, the release process can be automated inside GitHub Actions pipelines, or stays manual. + + + + diff --git a/content/py-pdf-owners.md b/content/pages/py-pdf-owners.md similarity index 99% rename from content/py-pdf-owners.md rename to content/pages/py-pdf-owners.md index e23f5fc..69e3d1e 100644 --- a/content/py-pdf-owners.md +++ b/content/pages/py-pdf-owners.md @@ -1,7 +1,6 @@ Title: Rules for py-pdf owners Date: 2023-04-18 17:10 Modified: 2023-04-18 17:10 -Category: py-pdf Tags: Governance Slug: py-pdf-owners Authors: Martin Thoma diff --git a/pelicanconf.py b/pelicanconf.py index 8e906b0..e8a4d86 100644 --- a/pelicanconf.py +++ b/pelicanconf.py @@ -1,19 +1,21 @@ +import logging + +logging.root.setLevel(logging.INFO) +logging.getLogger('pelican.utils').setLevel(logging.WARN) # avoids verbose "-> Copying ..." logs +logging.getLogger('tornado.access').setLevel(logging.WARN) # avoids verbose HTTP logs from livereload server +# Configure LOG_FORMAT to prefix it with "%(asctime)s [%(module)s]": +if logging.root.handlers: # handlers are only set the 2nd time this file is evaluated by Pelican + formatter = logging.root.handlers[0].formatter + formatter._fmt = formatter._style._fmt = "%(asctime)s [%(name)s] %(levelname)s %(message)s" + AUTHOR = "The py-pdf owners" SITENAME = "The py-pdf organization" -SITEURL = "" - -PATH = "content" TIMEZONE = "Europe/Berlin" - DEFAULT_LANG = "en" -# Feed generation is usually not desired when developing -FEED_ALL_ATOM = None -CATEGORY_FEED_ATOM = None -TRANSLATION_FEED_ATOM = None -AUTHOR_FEED_ATOM = None -AUTHOR_FEED_RSS = None +PATH = './content' +OUTPUT_PATH = './output' # Blogroll LINKS = ( @@ -32,5 +34,17 @@ DEFAULT_PAGINATION = 10 + +####################################### +# Config options specific to dev-mode: +####################################### + # Uncomment following line if you want document-relative URLs when developing # RELATIVE_URLS = True + +# Feed generation is usually not desired when developing +FEED_ALL_ATOM = None +CATEGORY_FEED_ATOM = None +TRANSLATION_FEED_ATOM = None +AUTHOR_FEED_ATOM = None +AUTHOR_FEED_RSS = None diff --git a/requirements.in b/requirements.in index 4705997..90f2d78 100644 --- a/requirements.in +++ b/requirements.in @@ -1,7 +1,9 @@ -pip-tools # brings pip-compile to update the requirements.txt ghp-import # publish blog on https://py-pdf.github.io/ +pip-tools # brings pip-compile to update the requirements.txt pre-commit # automatically apply style checks/autofixes # For the blog: -pelican +invoke +livereload markdown +pelican diff --git a/requirements.txt b/requirements.txt index 98bc158..1165a56 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,10 +1,10 @@ # -# This file is autogenerated by pip-compile with Python 3.11 +# This file is autogenerated by pip-compile with Python 3.8 # by the following command: # # pip-compile requirements.in # -blinker==1.5 +blinker==1.6 # via pelican build==0.10.0 # via pip-tools @@ -24,8 +24,14 @@ ghp-import==2.1.0 # via -r requirements.in identify==2.5.22 # via pre-commit +importlib-metadata==6.1.0 + # via markdown +invoke==2.0.0 + # via -r requirements.in jinja2==3.1.2 # via pelican +livereload==2.6.3 + # via -r requirements.in markdown==3.4.3 # via -r requirements.in markdown-it-py==2.2.0 @@ -56,7 +62,7 @@ python-dateutil==2.8.2 # via # ghp-import # pelican -pytz==2023.2 +pytz==2023.3 # via # feedgenerator # pelican @@ -65,13 +71,27 @@ pyyaml==6.0 rich==13.3.3 # via pelican six==1.16.0 - # via python-dateutil + # via + # livereload + # python-dateutil +tomli==2.0.1 + # via + # build + # pyproject-hooks +tornado==6.2 + # via livereload +typing-extensions==4.5.0 + # via + # blinker + # rich unidecode==1.3.6 # via pelican virtualenv==20.21.0 # via pre-commit wheel==0.40.0 # via pip-tools +zipp==3.15.0 + # via importlib-metadata # The following packages are considered to be unsafe in a requirements file: # pip diff --git a/tasks.py b/tasks.py index 4d592eb..5e3edde 100644 --- a/tasks.py +++ b/tasks.py @@ -6,6 +6,7 @@ from invoke import task from invoke.main import program +from livereload import Server from pelican import main as pelican_main from pelican.server import ComplexHTTPRequestHandler, RootedHTTPServer from pelican.settings import DEFAULT_CONFIG, get_settings_from_file @@ -96,8 +97,6 @@ def preview(c): @task def livereload(c): """Automatically reload browser tab upon file modification.""" - from livereload import Server - def cached_build(): cmd = "-s {settings_base} -e CACHE_CONTENT=true LOAD_CONTENT_CACHE=true" pelican_run(cmd.format(**CONFIG))