diff --git a/README.md b/README.md index 57a83ce..12f200d 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ ## Features - Directory hierarchy support -- Virtual directories: new books, authors, languages, decade issued, etc. +- Virtual directories/shelves: new books, authors, languages, decade issued, etc. - ePUB format: metadata extraction, thumbnail generation - PDF format: metadata extraction, thumbnail generation - "Lazy" updating of feeds. `lib2opds` re-generates feeds only when new files are added into the library @@ -18,13 +18,18 @@ `lib2opds` is distributed on PyPI. The best way to install it is with [pipx](https://pipx.pypa.io). -``` -pipx install lib2opds +```shell +$ pipx install lib2opds ``` ## How to use +Please read the manual frist: +```shell +$ man lib2opds ``` +Let's consider the following library directory: +```shell $ tree ./test-library/ ./test-library/ ├── Linux @@ -32,9 +37,13 @@ $ tree ./test-library/ └── Science Fiction ├── All Systems Red.epub └── I, Robot - Isaac Asimov.epub - +``` +Generate OPDS catalog and complimenting HTML site for the library directory: +```shell $ lib2opds --opds-base-uri "/opds/" --library-base-uri "/library/" --library-dir "./test-library" --opds-dir "./output" --generate-site-xslt - +``` +Get the following result: +```shell $ tree ./output/ ./output/ @@ -54,28 +63,25 @@ $ tree ./output/ └── index.xml ``` -`/etc/lib2opds.ini` is used by default and options can be overridden via command line arguments. +`/etc/lib2opds.ini` is used by default and options can be overridden via command line arguments. See `$ man 5 lib2opds.ini` for more details. -Example of configuration file for Nginx: +Now it is possible to serve it with any HTTP server. Example of configuration file for Nginx with HTTP Basic Authentication: ```nginx location /library { - alias /library-dir; + auth_basic "Library Area"; + auth_basic_user_file /etc/nginx/htpasswd; + alias /library-dir-path; } location /opds { auth_basic "Library Area"; auth_basic_user_file /etc/nginx/htpasswd; - alias /opds-dir; + alias /opds-dir-path; index index.xml; } - -location /opds/covers { - alias /opds-dir/covers; -} ``` - -Library location here is not protected with basic auth because of the bug in some e-book reader software. +Notice: There might be issues with some e-book reader software because of the library location protected with basic auth. ## Sidecar files diff --git a/lib2opds/__init__.py b/lib2opds/__init__.py index 493f741..6a9beea 100644 --- a/lib2opds/__init__.py +++ b/lib2opds/__init__.py @@ -1 +1 @@ -__version__ = "0.3.0" +__version__ = "0.4.0" diff --git a/man/lib2opds-sidecar-files.5 b/man/lib2opds-sidecar-files.5 new file mode 100644 index 0000000..6763005 --- /dev/null +++ b/man/lib2opds-sidecar-files.5 @@ -0,0 +1,44 @@ +.TH LIB2OPDS-SIDECAR-FILES 5 +.SH DESCRIPTION +.BR lib2opds (1) +detects sidecar files for the target e-book file and extracts metadata and cover from them. +For example, in case of +.BR some-book.epub +e-book file lib2opds will try to check for +.BR some-book.info +and +.BR some-book.cover +files. +.BR .cover +is just an image file. +.PP +.BR .info +sidecar files are basically INI-format files started with +.BR [Publication] +section. +.PP +The possible keys and their meanings are as follows: +.TP +.BR title +title of the book +.TP +.BR authors +comma-separated list of authors of the book +.TP +.BR description +description of the book +.TP +.BR language +language of the book +.TP +.BR issued +when was the book issued? +.TP +.BR publisher +What is publisher of the book +.TP +.BR identifier +What is identifier of the book, e.g. ISBN +.SH SEE ALSO +.BR lib2opds (1), +.BR lib2opds.ini (5) diff --git a/man/lib2opds.1 b/man/lib2opds.1 new file mode 100644 index 0000000..960bc3f --- /dev/null +++ b/man/lib2opds.1 @@ -0,0 +1,143 @@ +.TH LIB2OPDS 1 +.SH NAME +lib2opds \- static OPDS catalog generator for ebook library +.SH SYNOPSIS +.SY lib2opds +.OP options +.OP \-\-help +.OP \-\-version +.YS +.SH DESCRIPTION +.B lib2opds +generates OPDS catalog for local e-book library. +Additionally, it can generate HTML output with both options: XLST client-side templating for OPDS/Atom XML output or separate HTML files generation. +.SH OPTIONS +.TP +.BR \-\-help +print a help message and exit +.TP +.BR \-\-version +display version information and exit +.TP +.BR \-\-library-dir " "\fILIBRARY_DIR\fR +directory with your books +.TP +.BR \-\-opds-dir " "\fIOPDS_DIR\fR +target directory for OPDS feeds +.TP +.BR \-\-library-base-uri " "\fILIBRARY_BASE_URI\fR +base URI for serving books from the library, for example https://your-domain.com/library +.TP +.BR \-\-opds-base-uri " "\fIOPDS_BASE_URI\fR +base URI for OPDS, for example https://domain.example/opds +.TP +.BR \-\-library_title " "\fILIBRARY_TITLE\fR +library title +.TP +.BR \-\-clear-opds-dir +clear OPDS directory before generating result feeds +.TP +.BR \-\-invalidate-cache +clear cache directory before generating result feeds +.TP +.BR \-\-generate-site +generate static site additionally to OPDS catalog +.TP +.BR \-\-generate-site-xslt +generate HTML output with help of XSLT client-side processing of OPDS catalog +.TP +.BR \-\-cache-dir " "\fICACHE_DIR\fR +directory for caching ebook metadata +.TP +.BR \-c ", " \-\-config " "\fICONFIG\fR +config path +.TP +.BR \-u ", " \-\-update +force recreation of ODPS feeds +.SH EXAMPLES +Consider following directory with some structure and which contains ebook files: +.PP +.nf +.RS +$ tree ./test-library/ +./test-library/ +├── Linux +│ └── How Linux Works - Brian Ward.epub +└── Science Fiction + ├── All Systems Red.epub + └── I, Robot - Isaac Asimov.epub +.RE +.fi +.PP +Run +.B lib2opds +with the following options: +.PP +.nf +.RS +$ lib2opds --opds-base-uri "/opds/" --library-base-uri "/library/" --library-dir "./test-library" --opds-dir "./output" --generate-site-xslt +.RE +.fi +.PP +See the following output in the specified target directory for OPDS catalog: +.PP +.nf +.RS +$ tree ./output/ +./output/ + +├── assets +│ ├── acquisition-feed.xsl +│ ├── navigation-feed.xsl +│ └── style.css +├── covers +│ ├── a965b65e-85f9-4e98-a02b-4ff316869a2c.jpg +│ └── d738ea6d-f205-45e6-b09d-17d9b95c0286.jpg +├── feeds +│ ├── 142ccd52-436c-402f-8094-524fb20af9d3.xml +│ ├── 414562bf-c592-47f3-a94d-b01120ee22ca.xml +│ ├── 44d48843-196b-409b-9bd9-67d928505121.xml +... +│ └── fab6423d-a3ea-4027-8d84-b372fbef4503.xml +└── index.xml +.RE +.fi +.PP +.BR /etc/lib2opds.ini +is used by default. +Options specified in configuation file can be overridden via command line arguments. +.PP +Example of the Nginx configuration file: +.PP +.nf +.RS +location /library { + auth_basic "Library Area"; + auth_basic_user_file /etc/nginx/htpasswd; + alias /library-dir-path; +} + +location /opds { + auth_basic "Library Area"; + auth_basic_user_file /etc/nginx/htpasswd; + alias /opds-dir-path; + index index.xml; +} +.RE +.fi +.PP +Notice: There might be issues with some e-book reader software because of the library location protected with basic auth. +.SH FILES +.TP +.BR /etc/lib2opds.ini +Default system-wide configuration file. See +.BR lib2opds.ini (5) +for details on the syntax. +.TP +.BR "Sidecar files" +lib2opds detects sidecar files for the target e-book file and extracts metadata and cover from them. +.SH REPORTING BUGS +Please use the bug tracker on https://\:github.com/\:oxdef/\:lib2opds/\:issues to report bugs and feature requests. +.SH SEE ALSO +.BR lib2opds.ini (5), +.BR lib2opds-sidecar-files (5) diff --git a/man/lib2opds.ini.5 b/man/lib2opds.ini.5 new file mode 100644 index 0000000..b8ccdd7 --- /dev/null +++ b/man/lib2opds.ini.5 @@ -0,0 +1,82 @@ +.TH LIB2OPDS.ini 5 +.SH NAME +lib2opds.ini \- lib2opds configuration file +.SH SYNOPSIS +.SY /etc/lib2opds.ini +.YS +.SH DESCRIPTION +.BR lib2opds (1) +reads configuration options from the system-wide configuration file +.BR /etc/lib2opds.ini +, or the file specified with +.BR \-c ", " \-\-config " " +on the command line. +The file is in the INI format and started with +.BR [General] +section. +.PP +The possible keys and their meanings are as follows: +.TP +.BR library_dir +directory with your books +.TP +.BR opds_dir +target directory for OPDS feeds +.TP +.BR library_base_uri +base URI for serving books from the library, for example https://your-domain.com/library +.TP +.BR opds_base_uri +base URI for OPDS, for example https://domain.example/opds +.TP +.BR root_filename +root file name for the OPDS catalog, e.g. index.xml +.TP +.BR library_title +title of the library, e.g. "My Library" +.TP +.BR cover_width +width of cover images, e.g. 500 px +.TP +.BR cover_height +height of cover images, e.g. 500 px +.TP +.BR cover_quality +quality value for the result cover image file in JPEG format +.TP +.BR clear_opds_dir +clear OPDS directory before generating result feeds +.TP +.BR generate_site +generate static site additionally to OPDS catalog +.TP +.BR generate_site_xslt +generate HTML output with help of XSLT client-side processing of OPDS catalog +.TP +.BR generate_issued_feed +Should +.B lib2opds +generate the "Issued" feed? true/false +.TP +.BR generate_languages_feed +Should +.B lib2opds +generate the "Languages" feed? true/false +.BR generate_random_book_feed +Should +.B lib2opds +generate the "Random" feed? true/false +.TP +.BR publication_freshness_days +How many days should be from the adding of the ebook file to consider it new one, e.g. 14 +.TP +.BR cache_dir +directory for caching ebook metadata +.SH FILES +.TP +.BR /etc/lib2opds.ini +Default system-wide configuration file +.SH SEE ALSO +.BR lib2opds (1), +.BR lib2opds-sidecar-files (5) + diff --git a/pyproject.toml b/pyproject.toml index 7b78c9f..36ce8cd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,6 +45,11 @@ path = "lib2opds/__init__.py" [project.scripts] lib2opds = "lib2opds.__main__:cli" +[tool.hatch.build.targets.wheel.shared-data] +"man/lib2opds.1" = "share/man/man1/lib2opds.1" +"man/lib2opds.ini.5" = "share/man/man5/lib2opds.ini.5" +"man/lib2opds-sidecar-files.5" = "share/man/man5/lib2opds-sidecar-files.5" + [tool.black] line-length = 90 target-version = ['py311']