From d70e78bbdd9d9b5727f18a82fce08f20bdbbba19 Mon Sep 17 00:00:00 2001
From: Matthias Baumgartner <dev@igsor.net>
Date: Thu, 2 Mar 2023 10:26:29 +0100
Subject: readme and changelog

---
 README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 README.md

(limited to 'README.md')

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..da066f6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+
+The Black Star File System
+==========================
+
+
+### Developer tools setup
+
+#### Test coverage (coverage)
+
+Resources:
+* https://coverage.readthedocs.io/en/6.5.0/index.html
+* https://nedbatchelder.com/blog/200710/flaws_in_coverage_measurement.html
+
+Commands:
+$ pip install coverage
+$ coverage run ; coverage html ; xdg-open .htmlcov/index.html
+
+
+
+#### Static code analysis (pylint)
+
+Resources:
+* https://github.com/PyCQA/pylint
+* https://pylint.org/
+* https://pylint.pycqa.org/en/latest/user_guide/messages/messages_overview.html#messages-overview
+
+Commands:
+$ pip install pylint
+$ pylint bsfs
+
+
+
+#### Type analysis (mypy)
+
+Resources:
+* https://github.com/python/mypy
+* https://mypy.readthedocs.io/en/stable/
+
+Commands:
+$ pip install mypy
+$ mypy
+
+
+
+#### Documentation (sphinx)
+
+Resources:
+* 
+* 
+
+Commands:
+$ pip install ...
+$ 
+
+
+
+
-- 
cgit v1.2.3


From 48fd909f502d25cbe7ef7732c44734f593c6e022 Mon Sep 17 00:00:00 2001
From: Matthias Baumgartner <dev@igsor.net>
Date: Thu, 2 Mar 2023 14:57:49 +0100
Subject: README, CHANGELOG, and minor style fixes

---
 README.md | 64 ++++++++++++++++++++++++++++++---------------------------------
 1 file changed, 30 insertions(+), 34 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index da066f6..1956752 100644
--- a/README.md
+++ b/README.md
@@ -1,57 +1,53 @@
 
-The Black Star File System
-==========================
+# The Black Star File System
 
+The Black Star File System (BSFS) is a semantic file system, meaning that it organizes files
+by association, and can record files, their metadata and content in a structured manner.
 
-### Developer tools setup
 
-#### Test coverage (coverage)
+## Installation
 
-Resources:
-* https://coverage.readthedocs.io/en/6.5.0/index.html
-* https://nedbatchelder.com/blog/200710/flaws_in_coverage_measurement.html
+You can install BSFS via pip:
 
-Commands:
-$ pip install coverage
-$ coverage run ; coverage html ; xdg-open .htmlcov/index.html
+    $ pip install --extra-index-url https://pip.bsfs.io bsfs
 
 
+## Development
 
-#### Static code analysis (pylint)
+Set up a virtual environment:
 
-Resources:
-* https://github.com/PyCQA/pylint
-* https://pylint.org/
-* https://pylint.pycqa.org/en/latest/user_guide/messages/messages_overview.html#messages-overview
+    $ virtualenv env
+    $ source env/bin/activate
 
-Commands:
-$ pip install pylint
-$ pylint bsfs
+Install bsfs as editable from the git repository:
 
+    $ git clone https://git.bsfs.io/bsfs.git
+    $ cd bsfs
+    $ pip install -e .
 
+Install the following additional packages besides bsfs:
 
-#### Type analysis (mypy)
+    $ pip install coverage mypy pylint
+    $ pip install sphinx sphinx-copybutton furo
+    $ pip install build
 
-Resources:
-* https://github.com/python/mypy
-* https://mypy.readthedocs.io/en/stable/
+To ensure code style discipline, run the following commands:
 
-Commands:
-$ pip install mypy
-$ mypy
+    $ coverage run ; coverage html ; xdg-open .htmlcov/index.html
+    $ pylint bsfs
+    $ mypy
 
+To build the package, do:
 
+    $ python -m build
 
-#### Documentation (sphinx)
-
-Resources:
-* 
-* 
-
-Commands:
-$ pip install ...
-$ 
+To run only the tests (without coverage), run the following command from the **test folder**:
 
+    $ python -m unittest
 
+To build the documentation, run the following commands from the **doc folder**:
 
+    $ sphinx-apidoc -f -o source/api ../bsfs/ --module-first -d 1 --separate
+    $ make html
+    $ xdg-open build/html/index.html
 
-- 
cgit v1.2.3


From 3ae93a405724ca6b5ddeb0b458fcc95685f83f09 Mon Sep 17 00:00:00 2001
From: Matthias Baumgartner <dev@igsor.net>
Date: Sun, 5 Mar 2023 19:12:57 +0100
Subject: build fixes

---
 README.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 1956752..796c198 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,13 @@ Install bsfs as editable from the git repository:
     $ cd bsfs
     $ pip install -e .
 
-Install the following additional packages besides bsfs:
+If you want to develop (*dev*), run the tests (*test*), edit the 
+documentation (*doc*), or build a distributable (*build*),
+install bsfs with the respective extras:
+
+    $ pip install -e .[dev,doc,build,test]
+
+Or, you can manually install the following packages besides BSFS:
 
     $ pip install coverage mypy pylint
     $ pip install sphinx sphinx-copybutton furo
-- 
cgit v1.2.3