Reorganize docs into flat folder layout

docs/source/API-refactoring.md

@@ -1,46 +0,0 @@
-# API refactoring
-
-Building up to Evennia 1.0 and beyond, it's time to comb through the Evennia API for old cruft. This
-whitepage is for anyone interested to contribute with their views on what part of the API needs
-refactoring, cleanup or clarification (or extension!)
-
-Note that this is not a forum. To keep things clean, each opinion text should ideally present a
-clear argument or lay out a suggestion. Asking for clarification and any side-discussions should be
-held in chat or forum.
-
----
-
-### Griatch (Aug 13, 2019)
-
-This is how to enter an opinion. Use any markdown needed but stay within your section. Also remember
-to copy your text to the clipboard before saving since if someone else edited the wiki in the
-meantime you'll have to start over.
-
-### Griatch (Sept 2, 2019)
-
-I don't agree with removing explicit keywords as suggested by [Johnny on Aug 29 below](API-
-refactoring#reduce-usage-of-optionalpositional-arguments-aug-29-2019). Overriding such a method can
-still be done by `get(self, **kwargs)` if so desired, making the kwargs explicit helps IMO
-readability of the API. If just giving a generic `**kwargs`, one must read the docstring or even the
-code to see which keywords are valid.
-
-On the other hand, I think it makes sense to as a standard offer an extra `**kwargs` at the end of
-arg-lists for common methods that are expected to be over-ridden. This make the API more flexible by
-hinting to the dev that they could expand their own over-ridden implementation with their own
-keyword arguments if so desired.
-
----
-
-### Johnny 
-
-####  Reduce usage of optional/positional arguments (Aug 29, 2019)
-```
-# AttributeHandler
-def get(self, key=None, default=None, category=None, return_obj=False,
-            strattr=False, raise_exception=False, accessing_obj=None,
-            default_access=True, return_list=False):
-```
-Many classes have methods requiring lengthy positional argument lists, which are tedious and error-
-prone to extend and override especially in cases where not all arguments are even required. It would
-be useful if arguments were reserved for required inputs and anything else relegated to kwargs for
-easier passthrough on extension.

docs/source/Administrative-Docs.md

@@ -1,45 +0,0 @@
-# Administrative Docs
-
-The following pages are aimed at game administrators -- the higher-ups that possess shell access and
-are responsible for managing the game.
-
-### Installation and Early Life
-
-- [Choosing (and installing) an SQL Server](Choosing-An-SQL-Server)
-- [Getting Started - Installing Evennia](Getting-Started)
-- [Running Evennia in Docker Containers](Running-Evennia-in-Docker)
-- [Starting, stopping, reloading and resetting Evennia](Start-Stop-Reload)
-- [Keeping your game up to date](Updating-Your-Game)
- - [Resetting your database](Updating-Your-Game#resetting-your-database)
-- [Making your game available online](Online-Setup)
-  - [Hosting options](Online-Setup#hosting-options)
-  - [Securing your server with SSL/Let's Encrypt](Online-Setup#ssl)
-- [Listing your game](Evennia-Game-Index) at the online [Evennia game
-index](http://games.evennia.com)
-
-### Customizing the server
-
-- [Changing the Settings](Server-Conf#Settings-file) 
-    - [Available Master Settings](https://github.com/evennia/evennia/blob/master/evennia/settings_default.py)
-- [Change Evennia's language](Internationalization) (internationalization)
-- [Apache webserver configuration](Apache-Config) (optional)
-- [Changing text encodings used by the server](Text-Encodings)
-- [The Connection Screen](Connection-Screen)
-- [Guest Logins](Guest-Logins)
-- [How to connect Evennia to IRC channels](IRC)
-- [How to connect Evennia to RSS feeds](RSS)
-- [How to connect Evennia to Grapevine](Grapevine)
-- [How to connect Evennia to Twitter](How-to-connect-Evennia-to-Twitter)
-
-### Administrating the running game
-
-- [Supported clients](Client-Support-Grid) (grid of known client issues)
-- [Changing Permissions](Building-Permissions) of users
-- [Banning](Banning) and deleting users
-  - [Summary of abuse-handling tools](Banning#summary-of-abuse-handling-tools) in the default cmdset
-
-### Working with Evennia
-
-- [Setting up your work environment with version control](Version-Control)
-- [First steps coding with Evennia](First-Steps-Coding)
-- [Setting up a continuous integration build environment](Continuous-Integration)

docs/source/Builder-Docs.md

@@ -1,26 +0,0 @@
-# Builder Docs
-
-This section contains information useful to world builders. 
-
-### Building basics
-
-- [Default in-game commands](Default-Command-Help)
-- [Building Quick-start](Building-Quickstart)
-- [Giving build permissions to others](Building-Permissions)
-- [Adding text tags](TextTags)
-  - [Colored text](TextTags#coloured-text)
-  - [Clickable links](TextTags#clickable-links)
-  - [Inline functions](TextTags#inline-functions)
-- [Customizing the connection screen](Connection-Screen)
-
-### Advanced building and World building
-
-- [Overview of batch processors](Batch-Processors)
-  - [Batch-command processor](Batch-Command-Processor)
-  - [Batch-code processor](Batch-Code-Processor)
-- [Using the Spawner for individualizing objects](Spawner-and-Prototypes)
-- [Adding Zones](Zones)
-
-### The Tutorial world
-
-- [Introduction and setup](Tutorial-World-Introduction)

docs/source/Contributing-Docs.md

@@ -14,9 +14,40 @@ Markdown files are simple text files that can be edited with a normal text edito
 contain raw HTML directives (but that is very rarely needed). They primarly use
 the [Markdown][commonmark] syntax. See [the syntax section below](#Editing-syntax) for more help.
 
-> Note: Don't edit the files in `evennia/docs/source/api/`. These are auto-generated and your
-changes
-> will be lost.
+## Source file structure 
+
+The sources are organized into several rough categories, with only a few administrative documents
+at the root of `evennia/docs/source/`. The folders are named in singular form since they will 
+primarily be accessed as link refs (e.g. `Component/Account`)
+
+- `source/Components/` are docs describing separate Evennia building blocks, that is, things
+  that you can import and use. This extends and elaborates on what can be found out by reading
+  the api docs themselves. Example are documentation for `Accounts`, `Objects` and `Commands`.
+- `source/Concepts/` describes how larger-scale features of Evennia hang together - things that 
+  can't easily be broken down into one isolated component. This can be general descriptions of 
+  how Models and Typeclasses interact to the path a message takes from the client to the server 
+  and back.
+- `source/Setup/` holds detailed docs on installing, running and maintaining the Evennia server and 
+  the infrastructure around it. 
+- `source/Coding/` has help on how to interact with, use and navigate the Evennia codebase itself. 
+  This also has non-Evennia-specific help on general development concepts and how to set up a sane
+  development environment.
+- `source/Contribs/` holds documentation specifically for packages in the `evennia/contribs/` folder.
+  Any contrib-specific tutorials will be found here instead of in `Howtos`
+- `source/Howtos/` holds docs that describe how to achieve a specific goal, effect or 
+  result in Evennia. This is often on a tutorial or FAQ form and will refer to the rest of the 
+  documentation for further reading.
+  - `source/Howtos/StartingTutorial/` holds all documents part of the initial tutorial sequence.
+  
+  
+ Other files and folders:
+  - `source/api/` contains the auto-generated API documentation as `.rst` files. Don't edit these
+    files manually, your changes will be lost. 
+  - `source/_templates` and `source/_static` should not be modified unless adding a new doc-page 
+    feature or changing the look of the HTML documentation.
+  - `conf.py` holds the Sphinx configuration. It should usually not be modified except to update
+    the Evennia version on a new branch.
+    
 
 ## Building the docs locally
 

docs/source/Developer-Central.md

@@ -1,108 +0,0 @@
-# Developer Central
-
-
-This page serves as a central nexus for information on using Evennia as well as developing the
-library itself.
-
-### General Evennia development information
-
-- [Introduction to coding with Evennia](Coding-Introduction)
-- [Evennia Licensing FAQ](Licensing)
-- [Contributing to Evennia](Contributing)
-- [Code Style Guide](https://github.com/evennia/evennia/blob/master/CODING_STYLE.md) (Important!)
-- [Policy for 'MUX-like' default commands](Using-MUX-as-a-Standard)
-- [Setting up a Git environment for coding](Version-Control)
-- [Getting started with Travis and Github for continuous integration testing](Using-Travis)
-- [Planning your own Evennia game](Game-Planning)
-- [First steps coding Evennia](First-Steps-Coding)
-- [Translating Evennia](Internationalization#translating-evennia)
-- [Evennia Quirks](Quirks) to keep in mind.
-- [Directions for configuring PyCharm with Evennia on Windows](Setting-up-PyCharm)
-
-### Evennia API
-
-- [Directory Overview](Directory-Overview)
-- [evennia - the flat API](Evennia-API)
-  - [Running and Testing Python code](Execute-Python-Code)
-
-#### Core components and protocols
-
-- [Server and Portal](Portal-And-Server)  
-  - [Sessions](Sessions)
-  - [Configuration and module plugins](Server-Conf)
-- [The message path](Messagepath)
-  - [OOB](OOB) - Out-of-band communication
-  - [Inputfuncs](Inputfuncs)
-  - [Adding new protocols (client APIs) and services](Custom-Protocols)
-- [Adding new database models](New-Models)
-- [Running and writing unit tests](Unit-Testing)
-- [Running profiling](Profiling) 
-- [Debugging your code](Debugging)
-
-#### In-game Commands
-
-- [Command System overview](Command-System)
-- [Commands](Commands) 
-- [Command Sets](Command-Sets)
-- [Command Auto-help](Help-System#command-auto-help-system)
-
-#### Typeclasses and related concepts
-
-- [General about Typeclasses](Typeclasses)
-- [Objects](Objects)
-  - [Characters](Objects#characters)
-  - [Rooms](Objects#rooms)
-  - [Exits](Objects#exits)
-- [Accounts](Accounts)
-- [Communications](Communications)
-  - [Channels](Communications#channels)
-- [Scripts](Scripts)
-  - [Global Scripts](Scripts#Global-Scripts)
-  - [TickerHandler](TickerHandler)
-  - [utils.delay](Coding-Utils#utilsdelay)
-  - [MonitorHandler](MonitorHandler)
-- [Attributes](Attributes)
-- [Nicks](Nicks)
-- [Tags](Tags)
-  - [Tags for Aliases and Permissions](Tags#using-aliases-and-permissions)
-
-#### Web 
-
-- [Web features overview](Web-Features)
-- [The Webclient](Webclient)
-- [Web tutorials](Web-Tutorial)
-
-#### Other systems
-
-- [Locks](Locks)
-   - [Permissions](Locks#permissions)
-- [Help System](Help-System)
-- [Signals](Signals)
-- [General coding utilities](Coding-Utils)
-   - [Utils in evennia.utils.utils](api:evennia.utils.utils)
-- [Game time](Coding-Utils#game-time)
-- [Game Menus](EvMenu) (EvMenu)
-- [Text paging/scrolling](EvMore) (EvMore)
-- [Text Line Editor](EvEditor) (EvEditor)
-- [Text Tables](github:evennia.utils.evtable) (EvTable)
-- [Text Form generation](github:evennia.utils.evform) (EvForm)
-- [Spawner and Prototypes](Spawner-and-Prototypes)
-- [Inlinefuncs](TextTags#inline-functions)
-- [Asynchronous execution](Async-Process)
-
-### Developer brainstorms and whitepages
-
-- [API refactoring](API-refactoring), discussing what parts of the Evennia API needs a
-refactoring/cleanup/simplification
-- [Docs refactoring](Docs-refactoring), discussing how to reorganize and structure this wiki/docs
-better going forward
-- [Webclient brainstorm](Webclient-brainstorm), some ideas for a future webclient gui
-- [Roadmap](Roadmap), a tentative list of future major features
-- [Change log](https://github.com/evennia/evennia/blob/master/CHANGELOG.md) of big Evennia updates
-over time
-
-
-[group]: https://groups.google.com/forum/#!forum/evennia
-[online-form]:
-https://docs.google.com/spreadsheet/viewform?hl=en_US&formkey=dGN0VlJXMWpCT3VHaHpscDEzY1RoZGc6MQ#gid=0
-[issues]: https://github.com/evennia/evennia/issues

docs/source/Docs-refactoring.md

@@ -1,117 +0,0 @@
-# Docs refactoring
-
-This is a whitepage for free discussion about the wiki docs and refactorings needed. 
-
-Note that this is not a forum. To keep things clean, each opinion text should ideally present a
-clear argument or lay out a suggestion. Asking for clarification and any side-discussions should be
-held in chat or forum.
-
-### Griatch (Aug 13, 2019)
-
-This is how to make a discussion entry for the whitepage. Use any markdown formatting you need. Also
-remember to copy your work to the clipboard before saving the page since if someone else edited the
-page since you started, you'll have to reload and write again.
-
-#### (Sept 23, 2019)
-    
-[This (now closed) issue by DamnedScholar](https://github.com/evennia/evennia/issues/1431) gives the
-following suggestion:
-> I think it would be useful for the pages that explain how to use various features of Evennia to
-have explicit and easily visible links to the respective API entry or entries. Some pages do, but
-not all. I imagine this as a single entry at the top of the page [...].
-
-[This (now closed) issue by taladan](https://github.com/evennia/evennia/issues/1578) gives the
-following suggestion:
-> It would help me (and probably a couple of others) if there is a way to show the file path where a
-particular thing exists. Maybe up under the 'last edited' line we could have a line like:
-evennia/locks/lockhandler.py
-
-This would help in development to quickly refer to where a resource is located.
-   
-
-### Kovitikus (Sept. 11, 2019)
-
-[Batch Code](Batch-Code-Processor) should have a link in the developer area. It is currently only
-listed in the tutorials section as an afterthought to a tutorial title.
-
-***
-
-In regards to the general structure of each wiki page: I'd like to see a table of contents at the
-top of each one, so that it can be quickly navigated and is immediately apparent what sections are
-covered on the page. Similar to the current [Getting Started](Getting-Started) page.
-
-***
-
-The structuring of the page should also include a quick reference cheatsheet for certain aspects.
-Such as [Tags](Tags) including a quick reference section at the top that lists an example of every
-available method you can use in a clear and consistent format, along with a comment. Readers
-shouldn't have to decipher the article to gather such basic information and it should instead be
-available at first glance.
-
-Example of a quick reference:
-
-**Tags**
-```
-# Add a tag.
-obj.tags.add("label")
-
-# Remove a tag.
-obj.tags.remove("label")
-
-# Remove all tags.
-obj.tags.clear()
-
-# Search for a tag. Evennia must be imported first.
-store_result = evennia.search_tag("label")
-
-# Return a list of all tags.
-obj.tags.all()  
-```
-
-**Aliases**
-```
-# Add an alias.
-obj.aliases.add("label")
-
-ETC...
-```
-
-***
-
-In regards to comment structure, I often find that smushing together lines with comments to be too
-obscure. White space should be used to clearly delineate what information the comment is for. I
-understand that the current format is that a comment references whatever is below it, but newbies
-may not know that until they realize it.
-
-Example of poor formatting:
-```
-#comment
-command/code
-#comment
-command/code
-```
-
-Example of good formatting:
-```
-# Comment.
-command/code
-
-# Comment.
-command/code
-```
-
-### Sage (3/28/20)
-
-If I want to find information on the correct syntax for is_typeclass(), here's what I do:
-* Pop over to the wiki. Okay, this is a developer functionality. Let's try that.
-* Ctrl+F on Developer page. No results.
-* Ctrl+F on API page. No results. Ctrl+F on Flat API page. No results
-* Ctrl+F on utils page. No results.
-* Ctrl+F on utils.utils page. No results.
-* Ctrl+F in my IDE. Results.
-* Fortunately, there's only one result for def is_typeclass. If this was at_look, there would be
-several results, and I'd have to go through each of those individually, and most of them would just
-call return_appearance
-
-An important part of a refactor, in my opinion, is separating out the "Tutorials" from the
-"Reference" documentation.