Documentation and licensing updates. Hurrah for Read the Docs. :-)

Author: ntoll

LICENSE.md

@@ -0,0 +1,22 @@
+# Acknowledgements
+
+TextSmith wouldn't be possible without the work of many others who have made
+their code freely available for all to use. In no particular order I'd like to
+recognise the contributions of:
+
+* Cole Maclean for [aiosmtplib](https://github.com/cole/aiosmtplib).
+* Jonathan Slenders for [asyncio-redis](https://github.com/jonathanslenders/asyncio-redis).
+* Hsiaoming Yang for [flask-wtf](https://github.com/lepture/flask-wtf).
+* Phil Jones for [quart](https://github.com/pgjones/quart).
+* David Beazley for [sly](https://github.com/dabeaz/sly).
+* Hynek Schlawack for [structlog](https://github.com/hynek/structlog).
+* The PyTest project for [pytest](https://github.com/pytest-dev/pytest).
+* The Python Babel developers for [flask-babel](https://github.com/python-babel/flask-babel).
+* The Pallets project for [jinja](https://github.com/pallets/jinja).
+* The Sphinx team for [Sphinx](https://github.com/sphinx-doc/sphinx).
+* The folks at [Read the Docs](https://readthedocs.org/) for making it so easy
+  for documentation like this to be hosted online.
+* Innumerable [Python developers](https://python.org/) for many contributions
+  to such a flourishing ecosystem.
+* The folks behind [Redis](https://redis.io/).
+

docs/acknowledgements.md

@@ -0,0 +1,56 @@
+# API
+
+This API reference is automatically generated from the docstrings found within
+the source code. It's meant as an easy to use and easy to share window into the
+code base.
+
+Take a look around! The code is simple and short.
+
+## `textsmith.constants`
+
+```eval_rst
+.. automodule:: textsmith.constants
+    :members:
+```
+
+## `textsmith.datastore`
+
+```eval_rst
+.. automodule:: textsmith.datastore
+    :members:
+```
+
+## `textsmith.logic`
+
+```eval_rst
+.. automodule:: textsmith.logic
+    :members:
+```
+
+## `textsmith.log`
+
+```eval_rst
+.. automodule:: textsmith.log
+    :members:
+```
+
+## `textsmith.parser`
+
+```eval_rst
+.. automodule:: textsmith.parser
+    :members:
+```
+
+## `textsmith.pubsub`
+
+```eval_rst
+.. automodule:: textsmith.pubsub
+    :members:
+```
+
+## `textsmith.verbs`
+
+```eval_rst
+.. automodule:: textsmith.verbs
+    :members:
+```

docs/api.md

@@ -0,0 +1,3 @@
+# Architecture
+
+TBD

docs/architecture.md

@@ -0,0 +1,6 @@
+# Authors
+
+The following folks have made significant contributions to TextSmith's
+development:
+
+[Nicholas H.Tollervey](https://ntoll.org/) - creator and maintainer.

docs/authors.md

@@ -0,0 +1,42 @@
+# Code of Conduct
+
+We expect contributors to follow the Code of Conduct reproduced below (based
+upon that of the Python Software Foundation).
+
+The Python community is made up of members from around the globe with a diverse
+set of skills, personalities, and experiences. It is through these differences
+that our community experiences great successes and continued growth. When
+you're working with members of the community, we encourage you to follow these
+guidelines which help steer our interactions and strive to keep Python a
+positive, successful, and growing community.
+
+A member of the Python community is:
+
+## Open
+
+Members of the community are open to collaboration, whether it's on PEPs,
+patches, problems, or otherwise. We're receptive to constructive comment and
+criticism, as the experiences and skill sets of other members contribute to the
+whole of our efforts. We're accepting of all who wish to take part in our
+activities, fostering an environment where anyone can participate and everyone
+can make a difference.
+
+## Considerate
+
+Members of the community are considerate of their peers -- other Python users.
+We're thoughtful when addressing the efforts of others, keeping in mind that
+often times the labor was completed simply for the good of the community. We're
+attentive in our communications, whether in person or online, and we're tactful
+when approaching differing views.
+
+## Respectful
+
+Members of the community are respectful. We're respectful of others, their
+positions, their skills, their commitments, and their efforts. We're respectful
+of the volunteer efforts that permeate the Python community. We're respectful
+of the processes set forth in the community, and we work within them. When we
+disagree, we are courteous in raising our issues.
+
+Overall, we're good to each other. We contribute to this community not because
+we have to, but because we want to. If we remember that, these guidelines will
+come naturally.

docs/code_of_conduct.md

@@ -14,6 +14,11 @@
 import sys
 sys.path.insert(0, os.path.abspath('..'))
 
+# Markdown dammit!
+import recommonmark
+from recommonmark.transform import AutoStructify
+source_suffix = ".md"
+
 
 # -- Project information -----------------------------------------------------
 
@@ -33,7 +38,8 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.viewcode'
+    'sphinx.ext.viewcode',
+    "recommonmark",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -66,10 +72,22 @@
         'searchbox.html',
     ]
 }
+html_logo = 'icon.png'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-html_logo = 'icon.png'
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# See: https://recommonmark.readthedocs.io/en/latest/auto_structify.html for
+# information on using Sphinx directives within Markdown.
+github_doc_root = 'https://github.com/ntoll/textsmith/tree/master/docs/'
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+            'url_resolver': lambda url: github_doc_root + url,
+            'auto_toc_tree_section': 'Contents',
+            }, True)
+    app.add_transform(AutoStructify)

docs/conf.py

@@ -0,0 +1,53 @@
+# Contributing
+
+Hey! Many thanks for wanting to improve TextSmith.
+
+Contributions are welcome without prejudice from *anyone* irrespective of who
+you are. If you're thinking, "but they don't mean me", *then we especially mean
+YOU*. Good quality code and constructive engagement with respect, humour and
+intelligence is what you should aim for.
+
+* If you're from a background which isn't well-represented in most geeky
+  groups, get involved - *we want to help you make a difference*.
+* If you're from a background which *is* well-represented in most geeky
+  groups, get involved - *we want your help making a difference*.
+* If you're worried about not being technical enough, get involved - *your
+  fresh perspective will be invaluable*.
+* If you think you're an imposter, get involved.
+* If your day job isn't code, get involved.
+* This isn't a group of experts, just people. Get involved!
+* We are interested in literature, technology, community and creativity. If you
+  are too, get involved.
+* This is a new community. *No-one knows what they are doing*, so, get
+  involved.
+
+We expect contributors to follow the spirit of our
+[code_of_conduct](code_of_conduct.md).
+
+Feedback may be given for contributions and, where necessary, changes will
+be politely requested and discussed with the originating author. Respectful
+yet robust argument is most welcome.
+
+**Contributions are subject to the following caveats**: the contribution
+was created by the contributor who, by submitting the contribution, is
+confirming that they have the authority to submit the contribution and
+place it under the license as defined in the LICENSE file found within
+this repository.
+
+## Checklist
+
+* If your contribution includes non-obvious technical decision making please
+  make sure you document this.
+* Your code should be commented in *plain English* (British spelling).
+* If your contribution is for a major block of work and you've not done so
+  already, add yourself to the AUTHORS file following the convention found
+  therein.
+* We have 100% test coverage - include tests to maintain this!
+* **Before submitting code ensure coding standards and test coverage by
+  running**::
+```
+    make check
+```
+* If in doubt, ask a question. The only stupid question is the one that's never
+  asked.
+* Most importantly, **be creative and have fun!** :-)

docs/contributing.md

@@ -0,0 +1,67 @@
+# TextSmith
+
+A multi-user collaborative platform for creating and inhabiting text based
+literary worlds.
+
+**This is very much a work in progress.**
+
+## Developer Setup
+
+This project uses Python 3.7+.
+
+1. Ensure you have [Redis](https://redis.io/) installed.
+2. Clone the [repository](https://github.com/ntoll/textsmith).
+3. Create and start a new virtual environment.
+4. `pip install -r requirements.txt`
+5. Type `make` to see a list of common developer related tasks. For instance,
+   to run the full test suite and code checks type: `make check`.
+
+The application expects certain configuration settings to be found in the
+environment. These are (with default settings within parenthesis):
+
+* `TEXTSMITH_REDIS_HOST` (`"localhost"`) - the server running Redis.
+* `TEXTSMITH_REDIS_PORT` (`6379`) - the port to use to connect to Redis.
+* `TEXTSMITH_REDIS_PASSWORD` (`None`) - the password to use to connect to
+  Redis.
+* `TEXTSMITH_REDIS_POOLSIZE` (`10`) - the number of connections in the Redis
+  connection pool.
+* `TEXTSMITH_KEY` (`"CHANGEME"`) - the secret key used by the web application
+  for cryptographic operations.
+* `TEXTSMITH_DEBUG` (`False`) - the debug flag which results in detailed debug
+  information from the web application. This flag is assumed to be `True` if
+  any value is set in the environment variable.
+* `RECAPTCHA_PUBLIC_KEY` (`"CHANGEME"`) - the public key for the reCaptcha v2
+  challenge in the signup form.
+* `RECAPTCHA_PRIVATE_KEY` (`"CHANGEME"`) - the private key for the reCaptcha
+  v2 challenge in the signup form.
+* `TEXTSMITH_EMAIL_ADDRESS` (`"CHANGEME"`) - the email address of the account
+  TextSmith uses to send emails to users.
+* `TEXTSMITH_EMAIL_PASSWORD` (`"CHANGEME"`) - the password for the email
+  account TextSmith uses to send emails to users.
+* `TEXTSMITH_EMAIL_HOST` (`"CHANGEME"`) - the host for the email account
+  TextSmith uses to send emails to users.
+* `TEXTSMITH_EMAIL_PORT` (`"CHANGEME"`) - the port for the email account
+  TextSmith uses to send emails to users.
+
+To run TextSmith, `make run` and connect to the
+[local server](http://localhost:8000/) with your browser. If the `make` command
+doesn't work, try the following command from the shell:
+`hypercorn textsmith.app:app`.
+
+JSON based structured logging is emitted to stdout. Each log entry is on a
+single line and contains a timestamp and details of the system upon which the
+application is running.
+
+## Contents
+```eval_rst
+.. toctree::
+   :maxdepth: 2
+
+   contributing.md
+   code_of_conduct.md
+   architecture.md
+   api.md
+   license.md
+   authors.md
+   acknowledgements.md
+```