added documentation of user-facing features & more info for contributors

docs/contributor notes.rst

@@ -7,6 +7,15 @@ Project General
 
 This project follows `Semantic Versioning <http://semver.org/>`_.
 As it is currently in 1.x, you can be confident that console commands that work now will keep working in other 1.x versions. As the internal API is not currently intended for out-of-app use, there may be breaking changes in minor versions. However, the internal API should remain stable through patch versions, and future releases that expose this API should fully stabilise it.
+
+Internal Design Policy
+======================
+
+CFS_Manager follows an internal interaction model where commands from the CLI call upon the top-level manager, which calls upon file-system-object abstractions of each storage provider. These file system objects then interface with the provider's API via a wrapper written to increase the interface similarity, from the internal perspective, between the different providers. Generally, the provider's official Python SDK sits between the in-house wrapper and the provider's API.
+
+It is designed to be easily extended with new service providers, and ensures this by providing a very specific interface for the implementation of new file system classes. All file systems inherit from the carefully described Cloud File System class, and their methods are called interchangably by the top-level manager.
+
+It anticipates lower variance as information cascades upward. Each wrapper is extremely ideosyncratic because it talks to an API with a unique design philosophy. However, they use similar functions to pass similar types of data to their file system object. The file system object manipulate this data with different internal logic, but passing the same results up to the manager. The manager accepts data in several formats, but collapses them all into a standardised format. And when the CLI displays data to the user or accepts their commands, that user should see no indication that the provider APIs are all wildly different.
 
 Comment Policy
 ==============

docs/direction.rst

@@ -46,6 +46,8 @@ Goals
 
 * Migrating to a database using SQLAlchemy
 
+* Migrating to standard Python CLI libraries (eg, argparse)
+
 * When multiple files share a name, return list for user confirmation
 
 * Allow users to choose storage order

docs/features.rst

@@ -0,0 +1,47 @@
+*************
+Features List
+*************
+
+This page is for cataloguing all the exciting features of CFS_Manager.
+
+System Commands
+===============
+
+*After installing CFS_Manager, you should be able to run any of these in your shell/terminal/command-prompt*
+
+* ``cfs-config``
+
+Starts the configuration flow for CFS_Manager, allowing the user to choose defaults and allow access to their preferred storage providers.
+
+* ``cfsm`` or ``cfs-manager``
+
+Starts the CFS_Manager command line interface in the terminal window that is currently open.
+
+* ``cfs-do [command]``
+
+Initialises the virtual file system, performs the specified command, and then terminates. Allows the execution of one-off commands (such as downloading a specific file) without entering the embedded command line interface.
+
+* ``cfs-watch``
+
+Adds the current directory to the list of managed directories. Thus, its contents will be included any time a command to upload all managed files is given.
+
+User Interface
+==============
+
+*For the specific commands behind each of these options, open the CFS_Manager command line and use '--commands' for a full list*
+
+* Upload and download files and folders.
+
+* List all the files in your virtual file system.
+
+* Display the metadata associated with any given file, such as which storage provider it's hosted by and the date of last modification.
+
+* Optional autocompletion of filenames, to avoid having to write out really long titles.
+
+* Delete individual files or wipe all files from your virtual file system (with confirmation dialogue).
+
+* Display the amount of cloud space currently occupied by CFS_Manager, and the amount of free space available across platforms.
+
+* Detailed help page, about page, and list of CLI commands and flags.
+
+* Launch the project's license, documentation, or github repository from the command line.

docs/index.rst

@@ -1,5 +1,5 @@
-Welcome to CFS_Manager's documentation!
-=======================================
+CFS_Manager documentation
+=========================
 
 **Contents**
 
@@ -8,6 +8,7 @@ Welcome to CFS_Manager's documentation!
 
     README
     about
+    features
     contributor notes
     direction
     license