From 21bce0bae4cd1d07de60dec628893d855c43e715 Mon Sep 17 00:00:00 2001 From: Joey Hines Date: Mon, 30 Sep 2019 14:19:26 -0500 Subject: [PATCH] Added public documentation --- .gitignore | 2 +- GeoffreyApp/docs/.gitignore | 1 + GeoffreyApp/docs/public/Makefile | 19 ++ GeoffreyApp/docs/public/make.bat | 35 ++++ GeoffreyApp/docs/public/source/conf.py | 173 ++++++++++++++++++ .../docs/public/source/getting_started.rst | 102 +++++++++++ GeoffreyApp/docs/public/source/index.rst | 26 +++ GeoffreyApp/docs/public/source/new_in_2.0.rst | 45 +++++ GeoffreyApp/docs/source/getting_started.rst | 112 ------------ GeoffreyApp/docs/source/index.rst | 1 - 10 files changed, 402 insertions(+), 114 deletions(-) create mode 100644 GeoffreyApp/docs/public/Makefile create mode 100644 GeoffreyApp/docs/public/make.bat create mode 100644 GeoffreyApp/docs/public/source/conf.py create mode 100644 GeoffreyApp/docs/public/source/getting_started.rst create mode 100644 GeoffreyApp/docs/public/source/index.rst create mode 100644 GeoffreyApp/docs/public/source/new_in_2.0.rst delete mode 100644 GeoffreyApp/docs/source/getting_started.rst diff --git a/.gitignore b/.gitignore index 68fe285..3a58b38 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,4 @@ __pycache__/* /dist/* /GeoffreyApp.egg-info/* -docs.sh \ No newline at end of file +docs.sh diff --git a/GeoffreyApp/docs/.gitignore b/GeoffreyApp/docs/.gitignore index a007fea..7c4b346 100644 --- a/GeoffreyApp/docs/.gitignore +++ b/GeoffreyApp/docs/.gitignore @@ -1 +1,2 @@ build/* +public/build/* diff --git a/GeoffreyApp/docs/public/Makefile b/GeoffreyApp/docs/public/Makefile new file mode 100644 index 0000000..69fe55e --- /dev/null +++ b/GeoffreyApp/docs/public/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/GeoffreyApp/docs/public/make.bat b/GeoffreyApp/docs/public/make.bat new file mode 100644 index 0000000..4d9eb83 --- /dev/null +++ b/GeoffreyApp/docs/public/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/GeoffreyApp/docs/public/source/conf.py b/GeoffreyApp/docs/public/source/conf.py new file mode 100644 index 0000000..2a2bb3a --- /dev/null +++ b/GeoffreyApp/docs/public/source/conf.py @@ -0,0 +1,173 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Geoffrey' +copyright = '2019, ZeroHD' +author = 'ZeroHD' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '2.0' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'GeoffreyPublicdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'GeoffreyPublic.tex', 'GeoffreyPublic Documentation', + 'ZeroHD', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'geoffreypublic', 'GeoffreyPublic Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'GeoffreyPublic', 'GeoffreyPublic Documentation', + author, 'GeoffreyPublic', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] diff --git a/GeoffreyApp/docs/public/source/getting_started.rst b/GeoffreyApp/docs/public/source/getting_started.rst new file mode 100644 index 0000000..87640c3 --- /dev/null +++ b/GeoffreyApp/docs/public/source/getting_started.rst @@ -0,0 +1,102 @@ +.. _bot_quickstart: + +Geoffrey Bot Quickstart +*********************** + + + +Adding a Location +----------------- +First you must register with the bot if you are a new user:: + + ?register + +This allows Geoffrey to link your MC name with your Discord account. + +Then you can add your first base:: + +?add_base 500 550 + + +Your first base does not need a name, it defaults to "[Username]'s Base" + +If you want to specify a name:: + + ?add_base 500 550 My New Base + + +To delete a base:: + + ?delete "My Base" + +Adding a shop +------------- +A shop can be added like a base:: + + ?add_shop 500 550 + +or:: + + ?add_shop 500 550 Cool Shop + + +The following command then adds dirt to the shop with the price of 5 dirt for 1 diamond:: + + ?add_item Dirt 5 1 + +The `selling` command sorts by when an object was stocked. To restock an item you can use the following. This will make sure item +returns back to the top of `selling`. Do not abuse this or your shop may be removed. + + ?restock Dirt + +If you want to delete an item you can doby:: + + ?delete_item dirt + +To delete a shop:: + + ?delete "My shop" + + +If you have more than one shop, you need to specify the shop name. + +Searching in the database +------------------------- +The ``?find`` command is used to find bases and shops in Geoffrey. ``?find`` searches for both location names and owner names:: + + ?find ZeroHD + + +Then to find out more info about a location, use ``?info``:: + + ?info ZeroHD's Base + + + +``?selling`` can be used to find items for sale. Tip is better search for a subset of the item name +ig for `enderchests` search `ender`:: + + ?selling ender + + +You can also search around a position for locations with ``?find_around``:: + + ?find_around 0 0 + + +Editing Locations +----------------- +To rename a base/shop you can do the following (the quotations around the location names are important!):: + + ?edit_name "Cool New Name" "Current Name" + + +To move a location's position, use ``?edit_pos``:: + + ?edit_pos 420 69 Cool Base + + +To change the tunnel of a base, use ``?edit_tunnel``:: + + ?edit_tunnel North 545 + diff --git a/GeoffreyApp/docs/public/source/index.rst b/GeoffreyApp/docs/public/source/index.rst new file mode 100644 index 0000000..f120177 --- /dev/null +++ b/GeoffreyApp/docs/public/source/index.rst @@ -0,0 +1,26 @@ +.. GeoffreyPublic documentation master file, created by + sphinx-quickstart on Mon Sep 30 12:55:02 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Geoffrey: Minecraft Location Info +================================= + +Geoffrey was created to be an information source for bases, shops, towns and other locations on Minecraft severs. +This allows for users to quickly find each other's builds and find shops selling goods either from a discord bot +or a web interface + +The Geoffrey Discord bot can be used on a Discord server or in a private message with the bot. + +The web interface allows users to easily view location information. + +Any feedback should be sent to ZeroHD. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + getting_started + new_in_2.0 + + diff --git a/GeoffreyApp/docs/public/source/new_in_2.0.rst b/GeoffreyApp/docs/public/source/new_in_2.0.rst new file mode 100644 index 0000000..449e085 --- /dev/null +++ b/GeoffreyApp/docs/public/source/new_in_2.0.rst @@ -0,0 +1,45 @@ +.. _new_in_2.0: + +New In Geoffrey 2.0 +******************* + +Web Interface +============= +Geoffrey 2.0 features a web interface that allows users to easily access information about locations in Geoffrey. + +Currently, the web interface is read-only. All data still needs to be entered with the Discord bot. + +Multiple Owners Per Location +============================ +As requested by many, locations can now have more than one owner. All owners of a location have full power to modify +the location so only add owners you can trust!:: + + ?add_base 250 300 Triple D + ?add_owner Guy_Fieri Triple D + +New Location Types +================== +Many requested location types have been added to Geoffrey: + +Towns +----- +Towns are like bases except they can have multiple residents living at them.:: + + ?add_town 250 300 Flavor Town + ?add_resident Guy_Fieri Flavor Town + +Public Farms +------------ +Public farms are any location that can be used to farm a resource. This could be a mining desert or a skelly grinder. +Resources can be added to farms to allow others to find it easily.:: + + ?add_farm 250 300 Flavor Farm + ?add_resource "Bomb Flavors" Flavor Farm + ?find_farm sed + +Attraction +---------- +Locations that are for fun or good to look at. This would be used for minigame areas or impressive builds.:: + + ?add_attraction 250 500 Statue of Guy Fieri + diff --git a/GeoffreyApp/docs/source/getting_started.rst b/GeoffreyApp/docs/source/getting_started.rst deleted file mode 100644 index 90002f7..0000000 --- a/GeoffreyApp/docs/source/getting_started.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _getting_started: - -.. |br| raw:: html - -
- -*************** -Getting Started -*************** - -Requirements -############# -Versions shown have been tested to work - -* `Python 3.6.6`_ -* `Django 2.1.2`_ -* `Requests 2.20.0`_ -* `simplejson 3.16.0`_ - -.. _Python 3.6.6: https://www.python.org/ -.. _Django 2.1.2: https://pypi.org/project/Django/ -.. _Requests 2.20.0: https://pypi.org/project/requests2/ -.. _simplejson 3.16.0: https://pypi.org/project/simplejson/ - -Setup -##### -.. Note:: Geoffrey is a Django application. To install Geoffrey, you need to have a Django site already setup instructions to do that can be found `here`_ - -.. _here: https://docs.djangoproject.com/en/2.1/intro/tutorial01/ - -Installing GeoffreyApp From Source -********************************** -1. Download Geoffrey by cloning it -:: - - git clone https://git.etztech.xyz/ZeroHD/Geoffrey.git GeoffreyApp - -2. Change directories into GeoffreyApp -:: - - cd GeoffreyApp/ - -3. Install Geoffrey as a module -:: - - pip3 install -e . - - -Integrate Geoffrey Into a Django Project -****************************************** -1. In ``settings.py`` add ``GeoffreyApp`` to ``INSTALLED_APPS`` -:: - - INSTALLED_APPS = [ - 'GeoffreyApp', - ... - -2. Once installed, run the migrations to setup the database for the first time -:: - - python manage.py makemigrations - python manage.py migrate - -3. Then add the URLs to your projects's ``urls.py`` -:: - - path('GeoffreyApp/', include('GeoffreyApp.urls')), - -Setup Settings -************** -To setup your ``settings.py`` for Geoffrey, checkout :ref:`django_settings` - -Enable Username Updates -*********************** -Minecraft usernames in Geoffrey can be updated using the `update_mc_username` sub-command: -:: - - python manage.py update_mc_username - -To handle username updates automatically, an external scheduling program should be used. Below is an example of how to -do this with a Linux cron job: - -.. code-block:: bash - - #!/bin/bash - PATH_TO_GEOFFREY_MANAGE=/home/geoffrey/django/manage.py - PATH_TO_VENV=/home/geoffrey/venv - - source "$PATH_TO_VENV/bin/activate" - - python $PATH_TO_GEOFFREY_MANAGE update_mc_username - - deactivate - -The above script should be placed in the appropriate `/etc/cron.` directory. - - - - - - - - - - - - - - - - - diff --git a/GeoffreyApp/docs/source/index.rst b/GeoffreyApp/docs/source/index.rst index aed8b75..31a8024 100644 --- a/GeoffreyApp/docs/source/index.rst +++ b/GeoffreyApp/docs/source/index.rst @@ -15,4 +15,3 @@ bases, shops, items for sale, tunnels, towns, public farms and more! commands models bot_setup - bot_quickstart