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..c3efccf --- /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.webref/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.webref/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.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/README.md b/docs/README.md index 729cce2..47a6184 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,18 +18,19 @@ 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 ``` -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] @@ -49,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 @@ -59,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: @@ -70,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 @@ -83,4 +84,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 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? + +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. + +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 docs. +* 0.1: Basic read-only functionality diff --git a/docs/README_pypi.md b/docs/README_pypi.md index be8e2cc..77aba9b 100644 --- a/docs/README_pypi.md +++ b/docs/README_pypi.md @@ -2,34 +2,36 @@ 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 ``` -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] +secret_key = + [database] server = : databasename = @@ -37,7 +39,14 @@ username = password = ``` -Finally, run +`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())' +``` + +You can now start the web server by ```shell flask --app ppf.webref run @@ -45,55 +54,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 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 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/`. -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. + +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 docs. +* 0.1: Basic read-only functionality 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 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)