Merge pull request #2 from adrianschlatter/develop

* fix a problem that prevented links to documents from being rendered
* improve README
* add CONTRIBUTING and CODE OF CONDUCT

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 [email protected].
+
+[PSF Code of Conduct]: https://www.python.org/psf/conduct/

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.

docs/README.md

@@ -18,18 +18,19 @@ somewhere.
 </p>
 
 
-## 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 <username>
 
 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 <username> 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 <username>
 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 `<app.root_path>/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

docs/README_pypi.md

@@ -2,98 +2,112 @@
 
 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 = <your secret key here>
+
 [database]
 server = <server>:<port>
 databasename = <name of your jabref database>
 username = <username ppf.webref should use to access db>
 password = <password ppf.webref should use to access db>
 ```
 
-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
 ```
 
 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 <username>
 ```
 
-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 <username> 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 <username>
 ```
 
-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 `<app.root_path>/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

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)