<p align="center">
<img alt="logo" width="300" src=".github/images/logo_background.png">
</p>
<h1 align="center">
thumbnails-readme
</h1>
<h2 align="center">
Create thumbnails for raster and vector images in parent and its subdirectories and append them to the README.md file
</h2>
<p align="center">
<img alt="PyPI Version" src="https://img.shields.io/pypi/v/thumbnails-readme.svg">
<img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/thumbnails-readme.svg">
<img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/thumbnails-readme.svg">
<a href="https://repology.org/project/python:thumbnails-readme/versions">
<img alt="Packaging status" src="https://repology.org/badge/tiny-repos/python:thumbnails-readme.svg">
</a>
<a href="https://pepy.tech/project/thumbnails-readme">
<img alt="Downloads" src="https://pepy.tech/badge/thumbnails-readme">
</a>
<a href="https://github.com/firefly-cpp/thumbnails-readme/blob/master/LICENSE">
<img alt="GitHub License" src="https://img.shields.io/github/license/firefly-cpp/thumbnails-readme.svg">
</a>
</p>
<p align="center">
<img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/firefly-cpp/thumbnails-readme">
<img alt="GitHub Commit Activity" src="https://img.shields.io/github/commit-activity/w/firefly-cpp/thumbnails-readme.svg">
<a href='http://isitmaintained.com/project/firefly-cpp/thumbnails-readme "Average time to resolve an issue"'>
<img alt="Average time to resolve an issue" src="http://isitmaintained.com/badge/resolution/firefly-cpp/thumbnails-readme.svg">
</a>
<a href='http://isitmaintained.com/project/firefly-cpp/thumbnails-readme "Percentage of issues still open"'>
<img alt="Percentage of issues still open" src="http://isitmaintained.com/badge/open/firefly-cpp/thumbnails-readme.svg">
</a>
</p>
<p align="center">
<a href="#-github-action">🚀 GitHub Action</a> •
<a href="#-how-does-it-work">💡 How does it work?</a> •
<a href="#-installation">📦 Installation</a> •
<a href="#-additional-dependencies">🔗 Additional dependencies</a> •
<a href="#-example">📓 Example</a> •
<a href="#-use-cases">📂 Use Cases</a> •
<a href="#-license">🔑 License</a> •
<a href="#-thumbnails">📷 Thumbnails</a>
</p>
The `thumbnails-readme` package is a simple library devoted to automatically generating thumbnails from a directory. It is explicitly designed to create thumbnails from Git folders. The thumbnails are shown in the README file of that Git folder. 📁🌐📸
### 🔄 Multi-page PDFs are turned into .gif thumbnails
Current supported filetype extensions are: `.bmp`, `.gif`, `.ico`, `jpeg`, `.jpg`, `.png`, `.tga`, `.tiff`, `.webp`, `.pdf`, and `.svg`
## 🚀 GitHub Action
See the associated GitHub Action in the following repository: [thumbnails-readme-action](https://github.com/KukovecRok/thumbnails-readme-action).
## 💡 How does it work?
In the first step the program finds graphical material in your directories:
* ['fig1.pdf', 'fig2.pdf', 'fig3.pdf', 'fig4.pdf']
In the second step the program generates thumbnails for each material identified in folders.
In the third step the program appends thumbnails to the README file.
## 📦 Installation
To install `thumbnails-readme` with pip, use:
```sh
pip install thumbnails-readme
```
To install `thumbnails-readme` directly from the source code, use:
```sh
$ git clone https://github.com/firefly-cpp/thumbnails-readme.git
$ cd thumbnails-readme
$ poetry build
$ python setup.py install
```
To install `thumbnails-readme` on Alpine Linux, please use:
```sh
$ apk add py3-thumbnails-readme
```
To install `thumbnails-readme` on Arch Linux, use an [AUR helper](https://wiki.archlinux.org/title/AUR_helpers):
```sh
$ yay -Syyu python-thumbnails-readme
```
## 🔗 Additional dependencies
### Windows
Windows users have to download poppler for Windows. Add poppler path in your Python file (see the main example).
``` poppler_path = path/to/your/poppler/bin/ ```
For example: ```poppler_path = C:/Program Files/poppler-0.68.0/bin```
### Linux
Linux's users can install poppler-utils from the main repositories.
## 📓 Examples
### Examples of Usage
```python
# Maximum thumbnail size - lower the number, smaller the thumbnail
MAX_SIZE = (128, 128)
# PDF quality, lower the number, lower the quality
pdf_quality = 15
# Skiplist - which directories to ignore
skiplist = (
".git",
)
# Path to your directory
path = os.getcwd()
path = os.path.dirname(path)
# Path to the folder, you want new thumbnails to be placed in
path_to_thumbnails_folder = Path(path + "/image_thumbnails")
# Path to README.md file to be written to
path_to_readme = Path(path + "/README.md")
```
### Run the script
``` python
# Prepare thumbnails folder (check if exists, delete old thumbnails and create new ones)
thumbnails_readme.prepare_thumbnails_folder(path_to_thumbnails_folder)
# Prepare README.md file (check if exists, delete last modifications and place newly generated ones)
thumbnails_readme.prepare_readme(path_to_readme)
# Generate thumbnails
thumbnails_readme.crawl(path, path_to_readme, path_to_thumbnails_folder, MAX_SIZE, pdf_quality, skiplist, poppler_path)
```
## 📂 Use Cases
- [https://github.com/firefly-cpp/figures](https://github.com/firefly-cpp/figures)
- [https://github.com/firefly-cpp/posters](https://github.com/firefly-cpp/posters)
## 🔑 License
This package is distributed under the BSD-3-Clause license. This license can be found online at <http://www.opensource.org/licenses/bsd-3-clause/>.
## Disclaimer
This framework is provided as-is, and there are no guarantees that it fits your purposes or that it is bug-free. Use it at your own risk!
## 📷 Thumbnails
[](tests/example-long.pdf)
[](tests/example-pdf.pdf)
[](tests/example-svg.svg)
Raw data
{
"_id": null,
"home_page": "https://github.com/firefly-cpp/thumbnails-readme",
"name": "thumbnails-readme",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "thumbnails, README",
"author": "Rok Kukovec",
"author_email": "rok.kukovec@um.si",
"download_url": "https://files.pythonhosted.org/packages/ee/c9/0aa1c604ccf4f1f5fa22caaff43af4c379ca2a773195a1d1a161942cb713/thumbnails_readme-0.4.2.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img alt=\"logo\" width=\"300\" src=\".github/images/logo_background.png\">\n</p>\n\n<h1 align=\"center\">\n thumbnails-readme\n</h1>\n\n<h2 align=\"center\">\n Create thumbnails for raster and vector images in parent and its subdirectories and append them to the README.md file\n</h2>\n\n<p align=\"center\">\n <img alt=\"PyPI Version\" src=\"https://img.shields.io/pypi/v/thumbnails-readme.svg\">\n <img alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/thumbnails-readme.svg\">\n <img alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/thumbnails-readme.svg\">\n <a href=\"https://repology.org/project/python:thumbnails-readme/versions\">\n <img alt=\"Packaging status\" src=\"https://repology.org/badge/tiny-repos/python:thumbnails-readme.svg\">\n </a>\n <a href=\"https://pepy.tech/project/thumbnails-readme\">\n <img alt=\"Downloads\" src=\"https://pepy.tech/badge/thumbnails-readme\">\n </a>\n <a href=\"https://github.com/firefly-cpp/thumbnails-readme/blob/master/LICENSE\">\n <img alt=\"GitHub License\" src=\"https://img.shields.io/github/license/firefly-cpp/thumbnails-readme.svg\">\n </a>\n</p>\n\n<p align=\"center\">\n <img alt=\"GitHub repo size\" src=\"https://img.shields.io/github/repo-size/firefly-cpp/thumbnails-readme\">\n <img alt=\"GitHub Commit Activity\" src=\"https://img.shields.io/github/commit-activity/w/firefly-cpp/thumbnails-readme.svg\">\n <a href='http://isitmaintained.com/project/firefly-cpp/thumbnails-readme \"Average time to resolve an issue\"'>\n <img alt=\"Average time to resolve an issue\" src=\"http://isitmaintained.com/badge/resolution/firefly-cpp/thumbnails-readme.svg\">\n </a>\n <a href='http://isitmaintained.com/project/firefly-cpp/thumbnails-readme \"Percentage of issues still open\"'>\n <img alt=\"Percentage of issues still open\" src=\"http://isitmaintained.com/badge/open/firefly-cpp/thumbnails-readme.svg\">\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"#-github-action\">\ud83d\ude80 GitHub Action</a> \u2022\n <a href=\"#-how-does-it-work\">\ud83d\udca1 How does it work?</a> \u2022\n <a href=\"#-installation\">\ud83d\udce6 Installation</a> \u2022\n <a href=\"#-additional-dependencies\">\ud83d\udd17 Additional dependencies</a> \u2022\n <a href=\"#-example\">\ud83d\udcd3 Example</a> \u2022\n <a href=\"#-use-cases\">\ud83d\udcc2 Use Cases</a> \u2022\n <a href=\"#-license\">\ud83d\udd11 License</a> \u2022\n <a href=\"#-thumbnails\">\ud83d\udcf7 Thumbnails</a>\n</p>\n\nThe `thumbnails-readme` package is a simple library devoted to automatically generating thumbnails from a directory. It is explicitly designed to create thumbnails from Git folders. The thumbnails are shown in the README file of that Git folder. \ud83d\udcc1\ud83c\udf10\ud83d\udcf8\n\n### \ud83d\udd04 Multi-page PDFs are turned into .gif thumbnails\n\nCurrent supported filetype extensions are: `.bmp`, `.gif`, `.ico`, `jpeg`, `.jpg`, `.png`, `.tga`, `.tiff`, `.webp`, `.pdf`, and `.svg`\n\n## \ud83d\ude80 GitHub Action\n\nSee the associated GitHub Action in the following repository: [thumbnails-readme-action](https://github.com/KukovecRok/thumbnails-readme-action).\n\n## \ud83d\udca1 How does it work?\n\nIn the first step the program finds graphical material in your directories:\n* ['fig1.pdf', 'fig2.pdf', 'fig3.pdf', 'fig4.pdf']\n\nIn the second step the program generates thumbnails for each material identified in folders.\n\n\n\nIn the third step the program appends thumbnails to the README file.\n\n\n\n## \ud83d\udce6 Installation\n\nTo install `thumbnails-readme` with pip, use:\n\n```sh\npip install thumbnails-readme\n```\n\nTo install `thumbnails-readme` directly from the source code, use:\n\n```sh\n$ git clone https://github.com/firefly-cpp/thumbnails-readme.git\n$ cd thumbnails-readme\n$ poetry build\n$ python setup.py install\n```\n\nTo install `thumbnails-readme` on Alpine Linux, please use:\n\n```sh\n$ apk add py3-thumbnails-readme\n```\n\nTo install `thumbnails-readme` on Arch Linux, use an [AUR helper](https://wiki.archlinux.org/title/AUR_helpers):\n\n```sh\n$ yay -Syyu python-thumbnails-readme\n```\n\n## \ud83d\udd17 Additional dependencies\n\n### Windows\nWindows users have to download poppler for Windows. Add poppler path in your Python file (see the main example).\n\n``` poppler_path = path/to/your/poppler/bin/ ```\n\nFor example: ```poppler_path = C:/Program Files/poppler-0.68.0/bin```\n\n### Linux\nLinux's users can install poppler-utils from the main repositories.\n\n## \ud83d\udcd3 Examples\n\n### Examples of Usage\n\n```python\n# Maximum thumbnail size - lower the number, smaller the thumbnail\nMAX_SIZE = (128, 128)\n\n# PDF quality, lower the number, lower the quality\npdf_quality = 15\n\n# Skiplist - which directories to ignore\nskiplist = (\n \".git\",\n)\n\n# Path to your directory\npath = os.getcwd()\npath = os.path.dirname(path)\n\n# Path to the folder, you want new thumbnails to be placed in\npath_to_thumbnails_folder = Path(path + \"/image_thumbnails\")\n\n# Path to README.md file to be written to\npath_to_readme = Path(path + \"/README.md\")\n```\n\n### Run the script\n\n``` python\n# Prepare thumbnails folder (check if exists, delete old thumbnails and create new ones)\nthumbnails_readme.prepare_thumbnails_folder(path_to_thumbnails_folder)\n\n# Prepare README.md file (check if exists, delete last modifications and place newly generated ones)\nthumbnails_readme.prepare_readme(path_to_readme)\n\n# Generate thumbnails\nthumbnails_readme.crawl(path, path_to_readme, path_to_thumbnails_folder, MAX_SIZE, pdf_quality, skiplist, poppler_path)\n```\n## \ud83d\udcc2 Use Cases\n\n- [https://github.com/firefly-cpp/figures](https://github.com/firefly-cpp/figures)\n- [https://github.com/firefly-cpp/posters](https://github.com/firefly-cpp/posters)\n\n## \ud83d\udd11 License\n\nThis package is distributed under the BSD-3-Clause license. This license can be found online at <http://www.opensource.org/licenses/bsd-3-clause/>.\n\n## Disclaimer\n\nThis framework is provided as-is, and there are no guarantees that it fits your purposes or that it is bug-free. Use it at your own risk!\n\n## \ud83d\udcf7 Thumbnails\n\n[](tests/example-long.pdf)\n[](tests/example-pdf.pdf)\n[](tests/example-svg.svg)\n",
"bugtrack_url": null,
"license": null,
"summary": "Create thumbnails from Git folders",
"version": "0.4.2",
"project_urls": {
"Homepage": "https://github.com/firefly-cpp/thumbnails-readme",
"Repository": "https://github.com/firefly-cpp/thumbnails-readme"
},
"split_keywords": [
"thumbnails",
" readme"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c83b3056d6853679fbaedd6e04ac3c2dc64c4c0d3f569892254e4213a9dd0195",
"md5": "caddbf3f11335275fb0e8a5e4188966e",
"sha256": "49ddb75fd0ace605907c613033c54cf3b3f4027ee5b80a6db5f2bbfefca794e2"
},
"downloads": -1,
"filename": "thumbnails_readme-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "caddbf3f11335275fb0e8a5e4188966e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 7348,
"upload_time": "2024-09-11T09:17:43",
"upload_time_iso_8601": "2024-09-11T09:17:43.281895Z",
"url": "https://files.pythonhosted.org/packages/c8/3b/3056d6853679fbaedd6e04ac3c2dc64c4c0d3f569892254e4213a9dd0195/thumbnails_readme-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eec90aa1c604ccf4f1f5fa22caaff43af4c379ca2a773195a1d1a161942cb713",
"md5": "e077a549d29fef0ddb230f174454fa86",
"sha256": "f87dd6ea486b42a1cd987f24f527969ddf99537c55fa64435bc254514240b40d"
},
"downloads": -1,
"filename": "thumbnails_readme-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "e077a549d29fef0ddb230f174454fa86",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 7068,
"upload_time": "2024-09-11T09:17:49",
"upload_time_iso_8601": "2024-09-11T09:17:49.788080Z",
"url": "https://files.pythonhosted.org/packages/ee/c9/0aa1c604ccf4f1f5fa22caaff43af4c379ca2a773195a1d1a161942cb713/thumbnails_readme-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 09:17:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "firefly-cpp",
"github_project": "thumbnails-readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "thumbnails-readme"
}
JSON
