From 2c89cc645bd6245c9d53c3c107bdb54f7a6f1492 Mon Sep 17 00:00:00 2001 From: Andrew Brown Date: Sat, 17 Dec 2011 01:39:13 -0500 Subject: [PATCH] bumped docs to 0.4. Also lots of docs changes Added faq entry about exorbitant memory usage updated features section on the main page Added a "what overviewer is not" section on main page put new rendermodes on the options page re-worded some things under the custom rendermodes section --- docs/conf.py | 4 ++-- docs/faq.rst | 17 +++++++++++++++++ docs/index.rst | 46 ++++++++++++++++++++++++++++++++++++++++------ docs/options.rst | 45 +++++++++++++++++++++++++++++++++++++-------- 4 files changed, 96 insertions(+), 16 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ba5b27e..f079243 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,9 +48,9 @@ copyright = u'2010-2011 the Overviewer Team' # built documents. # # The short X.Y version. -version = "0.3" +version = "0.4" # The full version, including alpha/beta/rc tags. -release = "0.3.0" +release = "0.4" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/faq.rst b/docs/faq.rst index 1fc9130..9b51457 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -84,3 +84,20 @@ command lines, but information on how to do this has also not been written. On a related note, we also welcome contributions for a graphical interface for the Overviewer. + +The Overviewer is eating up all my memory! +------------------------------------------ + +We have written The Overviewer with memory efficiency in mind. On even the +largest worlds we have at our disposal to test with, it should not be taking +more than a gigabyte or two. It varies of course, that number is only an +estimate, but most computers with a reasonable amount of RAM should run just +fine. + +If you are seeing exorbitant memory usage, then it is likely either a bug or a +subtly corrupted world. Please file an issue or come talk to us on IRC so we can +take a look. See :ref:`help`. + +We have had a few reports of The Overviewer eating all a system's RAM but we +have been unable to figure out why or duplicate the issue. Any help or evidence +you can provide us will help us figure this out! diff --git a/docs/index.rst b/docs/index.rst index d2c717c..6da948d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,22 +28,55 @@ examples, see `The Example Wiki Page `) * Customizable textures! Pulls textures straight from your installed texture pack! -* Outputs a Google Map powered interface that is memory efficient, both in - generating and viewing. +* Generates a Google Maps powered map! + +* Runs on Linux, Windows, and Mac platforms! * Renders efficiently in parallel, using as many simultaneous processes as you want! -* Utilizes caching to speed up subsequent renderings of your world. +* *Only* requires: Python, Numpy, and PIL (all of which are included in the + Windows download!) + +* Utilizes caching to speed up subsequent renderings of your world. Only parts + that need re-rendering are re-rendered. * Throw the output directory up on a web server to share your Minecraft world - with everyone! + with the internet! + +* Run The Overviewer from a command line or on a cron schedule for constantly + updated maps! Run it for your Minecraft server world to provide your users + with a detailed map! + +What The Overviewer is not +-------------------------- +Full disclosure disclaimers of what The Overviewer is *not*. + +* It does not run fast. Because of the high level of detail, initial renders of + a world can take some time. Expect minutes for medium worlds, hours for large + to huge worlds. Subsequent renders are *much* faster due to the caching. + + Also note that speed is improving all the time. We continually make efficiency + improvements to The Overviewer. Besides, for the level of detail provided, + our users consider it worth the time! + +* Overviewer is not targeted at end users. We mainly see Overviewer fitting in + best with server operators, rendering their server's map for all users to + view. + + You are welcome to use Overviewer for your single player worlds, and it will + work just fine. However, since the only interface is currently command line + based, you will need to know a bit about the command line in order to operate + The Overviewer. Requirements ============ @@ -79,6 +112,7 @@ bad)**, head to the :doc:`Building ` page. **For all other platforms** you will need to build it yourself. :doc:`building`. +.. _help: Help ==== diff --git a/docs/options.rst b/docs/options.rst index d265517..ba07dea 100644 --- a/docs/options.rst +++ b/docs/options.rst @@ -106,11 +106,25 @@ Useful Options Powershell on Windows), you can also use a colon ':' or a forward slash '/' to separate the modes. - Incomplete list of common render-modes for your convenience: + **More information is available in the** :ref:`render-modes` **section of the + docs** + + List of built-in render-modes: * normal * lighting + * smooth-lighting + * smooth-night * night + * cave + + Built-in overlays: + * spawn + * mineral + + .. note:: + You can create custom rendermodes too! See the :ref:`custom-rendermodes` + section for more information! Example:: @@ -123,8 +137,6 @@ Useful Options Default: only render the normal mode - See the `Render Modes`_ section for more information. - .. cmdoption:: --list-rendermodes List the available render modes, and a short description of each, and exit. @@ -479,6 +491,8 @@ Less Useful Options There are **more settings** that cannot be specified on the command line. See the section below! +.. _settings-file: + Settings File ============= @@ -539,6 +553,8 @@ In addition to the `Command line options`_, you can specify these options. See the `Defining Custom Rendermodes`_ section for more information. +.. _render-modes: + Render Modes ============ @@ -574,6 +590,9 @@ relationships. Right now, it looks something like this: * lighting + * smooth-lighting + + * smooth-night * night * cave @@ -651,14 +670,22 @@ color. See the *settings.py* example below for an example usage of **minerals**. +.. _custom-rendermodes: + Defining Custom Rendermodes --------------------------- +Custom rendermodes allow you to take an existing rendermode, and define a new +one with a particular set of options. You can, for example, render two map +layers with the same mode, but with two different sets of options. You can do +this by defining a custom rendermode in your :ref:`settings-file` -Sometimes, you want to render two map layers with the same mode, but with two -different sets of options. For example, you way want to render a cave mode with -depth tinting, and another cave mode with lighting and no depth tinting. In this -case, you will want to define a 'custom' render mode that inherits from 'cave' -and uses the options you want. For example:: +.. note:: + You *must* use a :ref:`settings file ` in order to define custom rendermodes. + +Let's say you want to render a cave mode with depth tinting, and another cave +mode with lighting and no depth tinting. In this case, you can to define a +custom render mode that inherits from 'cave' and uses the options you want. Like +this:: custom_rendermodes = { 'cave-lighting': { @@ -674,6 +701,8 @@ and uses the options you want. For example:: rendermode = ['cave', 'cave-lighting'] +These lines would go in your settings file as written. + Each entry in ``custom_rendermodes`` starts with the mode name, and is followed by a dictionary of mode information, such as the parent mode and description (for your reference), a label for use on the map, as well as the options to