From 8893ae9c6663820f8e7b076e0c617a875ae93dc1 Mon Sep 17 00:00:00 2001 From: Adrian Schlatter <10478149+adrianschlatter@users.noreply.github.com> Date: Sun, 31 Dec 2023 17:50:40 +0100 Subject: [PATCH 1/4] Path problem fixed * for existence of pdf, we have to check the full file path * for returning a url, we have to take path relative to Flask root path --- src/ppf/webref/__init__.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/ppf/webref/__init__.py b/src/ppf/webref/__init__.py index f1b8123..33b18a3 100644 --- a/src/ppf/webref/__init__.py +++ b/src/ppf/webref/__init__.py @@ -133,12 +133,14 @@ def loadEntries(): for f in ['author', 'title', 'year', 'file']} for entry in db.session.execute(entryQ)] - basepath = Path('references') + flaskpath = Path('references') + basepath = Path(app.root_path) for entry in entries: if entry['file'] is not None: filepath = Path(split_by_unescaped_sep(entry['file'])[1]) - entry['file'] = basepath / filepath - if not entry['file'].exists() or filepath.is_absolute(): + entry['file'] = flaskpath / filepath + if not (basepath / entry['file']).exists() \ + or filepath.is_absolute(): entry['file'] = None return render_template('entry_table.tmpl', entries=entries) From 2ff27ebd6c8e56885863ccf49ff7383e7b91ed1e Mon Sep 17 00:00:00 2001 From: Adrian Schlatter <10478149+adrianschlatter@users.noreply.github.com> Date: Sun, 31 Dec 2023 18:11:33 +0100 Subject: [PATCH 2/4] docs --- docs/CODE_OF_CONDUCT.md | 16 ++++++ docs/CONTRIBUTING.md | 51 +++++++++++++++++++ docs/README.md | 38 ++++++++++++-- docs/README_pypi.md | 109 +++++++++++++++++++++++----------------- 4 files changed, 164 insertions(+), 50 deletions(-) create mode 100644 docs/CODE_OF_CONDUCT.md create mode 100644 docs/CONTRIBUTING.md diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..ea5ba91 --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,16 @@ +# Code of Conduct + +Everyone interacting in this project is expected to follow the [PSF Code of +Conduct]. This includes all infrastructure used in the development, such as +codebases, issue trackers, chat rooms, and mailing lists. + +In general, this means that everyone is expected to be **open**, +**considerate**, and **respectful** of others no matter what their position is +within the project. + + +## Reporting + +All incidents should be reported by emailing github@tambora.ch. + +[PSF Code of Conduct]: https://www.python.org/psf/conduct/ diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..afdc608 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,51 @@ +# How to contribute + +Thank for considering a contribution! Any help is greatly appreciated. + + +## Did you find an issue? + +* Check whether your issue has already been reported by searching under + [existing issues](https://github.com/adrianschlatter/ppf.datamatrix/issues). + +* If don't find an issue addressing the problem, open a new issue. + +* Choose a meaningful title, describe clearly what you consider to be a + problem. + +* If possible, provide example code or other means to make it easy for a + maintainer to reproduce your problem. + + +## Contributing Code + +You want to help with a bug or contribute a feature? The [development +docs](./dev/DEVDOCS.md) might help you along. + +You already have a solution for an issue or a new feature? All the better! A +pull request ("PR") is what you want to do. + +* Open a new + [pull-request](https://github.com/adrianschlatter/ppf.datamatrix/pulls) + with your patch. + +* Try to create PRs that address a specific issue/feature/topic. + +* Avoid PRs containing an assortment of unrelated fixes and features. Better + split it into separate PRs for each topic. + +* Clean up your code before creating a pull request: Remove code that you have + commented out for debugging, remove test code you have added. + +* Make sure the PR's description clearly describes the problem and your + solution. Include relevant issue numbers if appropriate. + +* You increase the chances of quick acceptance of your PR significantly if you + have taken measures to assure quality (such as writing and passing tests). + + +## Final remarks + +Currently, ppf.datamatrix is maintained in the spare time of a single person +having a family and a job. If you do not get immediate feedback to your issue +or pull request, please have some patience. diff --git a/docs/README.md b/docs/README.md index 729cce2..86eada9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,11 +18,13 @@ somewhere.

-## Installation +# Installation Prerequisite: You need JabRef to create, edit, and extend your library. -Install ppf.webref: +Install `ppf.webref` (or have a look at +[docker.webref](https://github.com/adrianschlatter/docker.webref) that provides +a docker container running `ppf.webref`): ```shell pip install ppf.webref @@ -83,4 +85,34 @@ flask --app ppf.webref passwd which will ask for and store (a salted hash of) the password in the user table. -Now we are able to login. +Now we are able to login, but the entry table will not provide links to our +documents. For `ppf.webref` to be able to serve the documents themselves, we +have to put them under `/references` (just place a symlink to +your JabRef library there). The app's root path is something like +`/usr/local/lib/python3.11/site-packages/ppf/webref/`. + + +# Still reading? + +If you read this far, you're probably not here for the first time. If you use +and like this project, would you consider giving it a Github Star? (The button +is at the top of this website.) If not, maybe you're interested in one of my +[my other +projects](https://github.com/adrianschlatter/ppf.sample/blob/develop/docs/list_of_projects.md)? + + +# Contributing + +Did you find a bug and would like to report it? Or maybe you've fixed it +already or want to help fixing it? That's great! Please read +[CONTRIBUTING](./CONTRIBUTING.md) to learn how to proceed from there. + +To help ascertain that contributing to this project is a pleasant experience, +we have established a [code of conduct](./CODE_OF_CONDUCT.md). You can expect +everyone to adhere to it, just make sure you do as well. + + +# Changelog + +* 0.1.1: Fix problem with path handling. Improve README.md. +* 0.1: Basic read-only functionality diff --git a/docs/README_pypi.md b/docs/README_pypi.md index be8e2cc..913a972 100644 --- a/docs/README_pypi.md +++ b/docs/README_pypi.md @@ -2,25 +2,25 @@ ppf.webref is a web app providing an interface to a [JabRef SQL database](https://docs.jabref.org/collaborative-work/sqldatabase). -It allows you to access your references from anywhere in the world and from -any device with a web browser. You do not need to install Java, you -do not need to install an app. Any non-archaic phone, tablet, PC, Mac, or -Raspberry Pi will do. +Access your references from anywhere in the world and from any device with a +web browser. You do not need to install Java, you do not need to install an +app. Any non-archaic phone, tablet, PC, Mac, or Raspberry Pi will do. -Create a JabRef database (using your normal JabRef) and configure ppf.webref -to point to this database. Voila: Your references just became accessible -worldwide. +Create a JabRef database (using your normal JabRef) and point ppf.webref to +this database. Voila: Your references just became accessible worldwide. Note: ppf.webref provides *read-only* access to your library. To add, edit, or delete entries from your library, you still need a standard JabRef installation somewhere. -## Installation +# Installation Prerequisite: You need JabRef to create, edit, and extend your library. -Install ppf.webref: +Install `ppf.webref` (or have a look at +[docker.webref](https://github.com/adrianschlatter/docker.webref) that provides +a docker container running `ppf.webref`): ```shell pip install ppf.webref @@ -30,6 +30,9 @@ Then, tell ppf.webref about your database by adding a section as follows to `~/.config/ppf.webref/ppf.webref.conf` (create it if it does not exist): ``` +[flask] +secret_key = + [database] server = : databasename = @@ -37,6 +40,13 @@ username = password = ``` +`secret_key` is needed to encrypt cookies. Set it to a random string, e.g. by +running this snippet: + +```shell +python -c 'import secrets; print(secrets.token_hex())' +``` + Finally, run ```shell @@ -45,55 +55,60 @@ flask --app ppf.webref run and point your webbrowser to http://localhost:5000. -This will start ppf.webref on your local machine which is nice for testing. +[This will start ppf.webref on your local machine which is nice for testing. To get the most out of ppf.webref, you will probably want to run ppf.webref on -a web server. +a web server.] -As we have not created any users yet, we can't login. To create -users, open your JabRef database (the one named in the config file above) -and run this sql-code (make sure you don't have a table with this name -already): +ppf.webref will present a login form. However, as we have not created any users +yet, we can't login. To create a user, run: -``` -create table user ( - id INT auto_increment, - username varchar(20) character set utf8 not null, - password char(80) character set ascii not null, - primary key (id), - unique(username) -) +```shell +flask --app ppf.webref useradd ``` -Now we have a user table but no users in it, yet. Let's find a password and -hash it with the following python code (of course, we replace the dummy -password with your own password beforehand): +This will: -``` -import bcrypt +* create a table 'user' in your db if it does not exist, yet +* register user in user table -password = 'This is my password' +To set a password for this new user or to change the password of an existing +user, do -bytes = password.encode('utf-8') -salt = bcrypt.gensalt() -print(bcrypt.hashpw(bytes, salt)) +```shell +flask --app ppf.webref passwd ``` -The output looks something like this: +which will ask for and store (a salted hash of) the password in the +user table. -``` -b'$2b$12$1royHRBq6o/mbDdO7LjR8eaThWYErI6HLLdn7MBfajtpRLlwWSJ8m' -``` +Now we are able to login, but the entry table will not provide links to our +documents. For `ppf.webref` to be able to serve the documents themselves, we +have to put them under `/references` (just place a symlink to +your JabRef library there). The app's root path is something like +`/usr/local/lib/python3.11/site-packages/ppf/webref/`. -Now add your user to the user table in you JabRef database using this sql-code -(again, replace "webref" with your username and the password hash with the -hash you generated above): -``` -insert into user (username, password) -values ( - "webref", - "$2b$12$1royHRBq6o/mbDdO7LjR8eaThWYErI6HLLdn7MBfajtpRLlwWSJ8m" -); -``` +# Still reading? + +If you read this far, you're probably not here for the first time. If you use +and like this project, would you consider giving it a Github Star? (The button +is at the top of this website.) If not, maybe you're interested in one of my +[my other +projects](https://github.com/adrianschlatter/ppf.sample/blob/develop/docs/list_of_projects.md)? + + +# Contributing + +Did you find a bug and would like to report it? Or maybe you've fixed it +already or want to help fixing it? That's great! Please read +[CONTRIBUTING](./CONTRIBUTING.md) to learn how to proceed from there. + +To help ascertain that contributing to this project is a pleasant experience, +we have established a [code of conduct](./CODE_OF_CONDUCT.md). You can expect +everyone to adhere to it, just make sure you do as well. + + +# Changelog -Now we are ready to go. +* 0.1.1: Fix problem with path handling. Improve README.md. +* 0.1: Basic read-only functionality From 79c7363c5ecbb88fb96dd6dc3dfe55efed0702ae Mon Sep 17 00:00:00 2001 From: Adrian Schlatter <10478149+adrianschlatter@users.noreply.github.com> Date: Mon, 1 Jan 2024 23:05:38 +0100 Subject: [PATCH 3/4] README.md --- docs/README.md | 23 +++++++++++------------ docs/README_pypi.md | 23 +++++++++++------------ 2 files changed, 22 insertions(+), 24 deletions(-) diff --git a/docs/README.md b/docs/README.md index 86eada9..47a6184 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,8 +30,7 @@ a docker container running `ppf.webref`): pip install ppf.webref ``` -Then, tell ppf.webref about your database by adding a section as follows to -`~/.config/ppf.webref/ppf.webref.conf` (create it if it does not exist): +Then, create the config file `~/.config/ppf.webref/ppf.webref.conf`: ``` [flask] @@ -51,7 +50,7 @@ running this snippet: python -c 'import secrets; print(secrets.token_hex())' ``` -Finally, run +You can now start the web server by ```shell flask --app ppf.webref run @@ -61,7 +60,7 @@ and point your webbrowser to http://localhost:5000. [This will start ppf.webref on your local machine which is nice for testing. To get the most out of ppf.webref, you will probably want to run ppf.webref on -a web server.] +a server.] ppf.webref will present a login form. However, as we have not created any users yet, we can't login. To create a user, run: @@ -72,7 +71,7 @@ flask --app ppf.webref useradd This will: -* create a table 'user' in your db if it does not exist, yet +* create a table 'user' in your db if it does not exist yet * register user in user table To set a password for this new user or to change the password of an existing @@ -85,11 +84,11 @@ flask --app ppf.webref passwd which will ask for and store (a salted hash of) the password in the user table. -Now we are able to login, but the entry table will not provide links to our -documents. For `ppf.webref` to be able to serve the documents themselves, we -have to put them under `/references` (just place a symlink to -your JabRef library there). The app's root path is something like -`/usr/local/lib/python3.11/site-packages/ppf/webref/`. +Now we are able to login, but the entry table will not provide clickable links +so you can easily open your documents. For `ppf.webref` to be able to serve the +documents themselves, we have to put them under `/references` +(just place a symlink to your JabRef library there). The app's root path is +something like `/usr/local/lib/python3.11/site-packages/ppf/webref/`. # Still reading? @@ -105,7 +104,7 @@ projects](https://github.com/adrianschlatter/ppf.sample/blob/develop/docs/list_o Did you find a bug and would like to report it? Or maybe you've fixed it already or want to help fixing it? That's great! Please read -[CONTRIBUTING](./CONTRIBUTING.md) to learn how to proceed from there. +[CONTRIBUTING](./CONTRIBUTING.md) to learn how to proceed. To help ascertain that contributing to this project is a pleasant experience, we have established a [code of conduct](./CODE_OF_CONDUCT.md). You can expect @@ -114,5 +113,5 @@ everyone to adhere to it, just make sure you do as well. # Changelog -* 0.1.1: Fix problem with path handling. Improve README.md. +* 0.1.1: Fix problem with path handling. Improve docs. * 0.1: Basic read-only functionality diff --git a/docs/README_pypi.md b/docs/README_pypi.md index 913a972..77aba9b 100644 --- a/docs/README_pypi.md +++ b/docs/README_pypi.md @@ -26,8 +26,7 @@ a docker container running `ppf.webref`): pip install ppf.webref ``` -Then, tell ppf.webref about your database by adding a section as follows to -`~/.config/ppf.webref/ppf.webref.conf` (create it if it does not exist): +Then, create the config file `~/.config/ppf.webref/ppf.webref.conf`: ``` [flask] @@ -47,7 +46,7 @@ running this snippet: python -c 'import secrets; print(secrets.token_hex())' ``` -Finally, run +You can now start the web server by ```shell flask --app ppf.webref run @@ -57,7 +56,7 @@ and point your webbrowser to http://localhost:5000. [This will start ppf.webref on your local machine which is nice for testing. To get the most out of ppf.webref, you will probably want to run ppf.webref on -a web server.] +a server.] ppf.webref will present a login form. However, as we have not created any users yet, we can't login. To create a user, run: @@ -68,7 +67,7 @@ flask --app ppf.webref useradd This will: -* create a table 'user' in your db if it does not exist, yet +* create a table 'user' in your db if it does not exist yet * register user in user table To set a password for this new user or to change the password of an existing @@ -81,11 +80,11 @@ flask --app ppf.webref passwd which will ask for and store (a salted hash of) the password in the user table. -Now we are able to login, but the entry table will not provide links to our -documents. For `ppf.webref` to be able to serve the documents themselves, we -have to put them under `/references` (just place a symlink to -your JabRef library there). The app's root path is something like -`/usr/local/lib/python3.11/site-packages/ppf/webref/`. +Now we are able to login, but the entry table will not provide clickable links +so you can easily open your documents. For `ppf.webref` to be able to serve the +documents themselves, we have to put them under `/references` +(just place a symlink to your JabRef library there). The app's root path is +something like `/usr/local/lib/python3.11/site-packages/ppf/webref/`. # Still reading? @@ -101,7 +100,7 @@ projects](https://github.com/adrianschlatter/ppf.sample/blob/develop/docs/list_o Did you find a bug and would like to report it? Or maybe you've fixed it already or want to help fixing it? That's great! Please read -[CONTRIBUTING](./CONTRIBUTING.md) to learn how to proceed from there. +[CONTRIBUTING](./CONTRIBUTING.md) to learn how to proceed. To help ascertain that contributing to this project is a pleasant experience, we have established a [code of conduct](./CODE_OF_CONDUCT.md). You can expect @@ -110,5 +109,5 @@ everyone to adhere to it, just make sure you do as well. # Changelog -* 0.1.1: Fix problem with path handling. Improve README.md. +* 0.1.1: Fix problem with path handling. Improve docs. * 0.1: Basic read-only functionality From ff71aec757fdbd7c329f4f3d6ccf6c153b3bee81 Mon Sep 17 00:00:00 2001 From: Adrian Schlatter <10478149+adrianschlatter@users.noreply.github.com> Date: Mon, 1 Jan 2024 23:07:58 +0100 Subject: [PATCH 4/4] CONTRIBUTIGN.md * ppf.datamatrix should be ppf.webref (copy & paste error) * fixed link to dev docs --- docs/CONTRIBUTING.md | 6 +++--- docs/{DevNotes.md => dev/DEVDOCS.md} | 0 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/{DevNotes.md => dev/DEVDOCS.md} (100%) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index afdc608..c3efccf 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -6,7 +6,7 @@ Thank for considering a contribution! Any help is greatly appreciated. ## Did you find an issue? * Check whether your issue has already been reported by searching under - [existing issues](https://github.com/adrianschlatter/ppf.datamatrix/issues). + [existing issues](https://github.com/adrianschlatter/ppf.webref/issues). * If don't find an issue addressing the problem, open a new issue. @@ -26,7 +26,7 @@ You already have a solution for an issue or a new feature? All the better! A pull request ("PR") is what you want to do. * Open a new - [pull-request](https://github.com/adrianschlatter/ppf.datamatrix/pulls) + [pull-request](https://github.com/adrianschlatter/ppf.webref/pulls) with your patch. * Try to create PRs that address a specific issue/feature/topic. @@ -46,6 +46,6 @@ pull request ("PR") is what you want to do. ## Final remarks -Currently, ppf.datamatrix is maintained in the spare time of a single person +Currently, ppf.webref is maintained in the spare time of a single person having a family and a job. If you do not get immediate feedback to your issue or pull request, please have some patience. diff --git a/docs/DevNotes.md b/docs/dev/DEVDOCS.md similarity index 100% rename from docs/DevNotes.md rename to docs/dev/DEVDOCS.md