commit d14624f7edaec2884e27365e66fcccfe4f5dff0a Author: ErickSkrauch Date: Fri Feb 6 23:09:41 2015 +0300 Initial commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7c0848f --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +### My idea folder +/.idea + +### BUILD FOLDER +/build \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..97f472f --- /dev/null +++ b/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Elybydocs.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Elybydocs.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Elybydocs" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Elybydocs" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..e051d71 --- /dev/null +++ b/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source +set I18NSPHINXOPTS=%SPHINXOPTS% source +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +%SPHINXBUILD% 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 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Elybydocs.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Elybydocs.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/source/_static/favicon.ico b/source/_static/favicon.ico new file mode 100644 index 0000000..f368d08 Binary files /dev/null and b/source/_static/favicon.ico differ diff --git a/source/_static/minecraft-auth/authlib-install.png b/source/_static/minecraft-auth/authlib-install.png new file mode 100644 index 0000000..7721cfd Binary files /dev/null and b/source/_static/minecraft-auth/authlib-install.png differ diff --git a/source/_static/minecraft-auth/authlib/authlib-1.3.1.jar b/source/_static/minecraft-auth/authlib/authlib-1.3.1.jar new file mode 100644 index 0000000..d16a1e8 Binary files /dev/null and b/source/_static/minecraft-auth/authlib/authlib-1.3.1.jar differ diff --git a/source/_static/minecraft-auth/authlib/authlib-1.3.jar b/source/_static/minecraft-auth/authlib/authlib-1.3.jar new file mode 100644 index 0000000..a77e09b Binary files /dev/null and b/source/_static/minecraft-auth/authlib/authlib-1.3.jar differ diff --git a/source/_static/minecraft-auth/authlib/authlib-1.5.13.jar b/source/_static/minecraft-auth/authlib/authlib-1.5.13.jar new file mode 100644 index 0000000..070ce33 Binary files /dev/null and b/source/_static/minecraft-auth/authlib/authlib-1.5.13.jar differ diff --git a/source/_static/minecraft-auth/authlib/authlib-1.5.16.jar b/source/_static/minecraft-auth/authlib/authlib-1.5.16.jar new file mode 100644 index 0000000..945894e Binary files /dev/null and b/source/_static/minecraft-auth/authlib/authlib-1.5.16.jar differ diff --git a/source/_static/minecraft-auth/authlib/authlib-1.5.17.jar b/source/_static/minecraft-auth/authlib/authlib-1.5.17.jar new file mode 100644 index 0000000..f8d47ad Binary files /dev/null and b/source/_static/minecraft-auth/authlib/authlib-1.5.17.jar differ diff --git a/source/_static/minecraft-auth/installing_by_inclasstranslator.png b/source/_static/minecraft-auth/installing_by_inclasstranslator.png new file mode 100644 index 0000000..9e44742 Binary files /dev/null and b/source/_static/minecraft-auth/installing_by_inclasstranslator.png differ diff --git a/source/_static/style.css b/source/_static/style.css new file mode 100644 index 0000000..5feaa7a --- /dev/null +++ b/source/_static/style.css @@ -0,0 +1,28 @@ +@import url(http://fonts.googleapis.com/css?family=Roboto+Condensed&subset=cyrillic,latin); + +body { + background: #ebe8e1!important; +} + +h1, h2, h3, h4, h5, h6, legend { + font-family: "Roboto Condensed", "Roboto Slab", sans-serif; + font-weight: normal; +} + +.wy-side-nav-search, +.wy-nav-top { + background-color: #207E5C; +} + +.wy-menu-vertical a:active { + background-color: #1A6449; +} + +.wy-nav-side { + background-color: #232323; +} + +.wy-table-responsive table td, +.wy-table-responsive table th { + white-space: normal; +} \ No newline at end of file diff --git a/source/_templates/layout.html b/source/_templates/layout.html new file mode 100644 index 0000000..fc50f09 --- /dev/null +++ b/source/_templates/layout.html @@ -0,0 +1,5 @@ +{# layout.html #} +{# Import the theme's layout. #} +{% extends "!layout.html" %} + +{% set css_files = css_files + ['_static/style.css'] %} \ No newline at end of file diff --git a/source/conf.py b/source/conf.py new file mode 100644 index 0000000..0f77cd8 --- /dev/null +++ b/source/conf.py @@ -0,0 +1,260 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Ely.by docs documentation build configuration file, created by +# sphinx-quickstart on Sun Feb 1 22:04:01 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import sphinx_rtd_theme + +# 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. +#sys.path.insert(0, os.path.abspath('.')) + +# -- 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 of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Документация Ely.by' +copyright = '2015, ErickSkrauch' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = 'ru' + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'monokai' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- 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 themes here, relative to this directory. +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +html_favicon = '_static/favicon.ico' + +# 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'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Elybydocsdoc' + + +# -- 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': '', +} + +# 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 = [ + ('index', 'Elybydocs.tex', 'Ely.by docs Documentation', + 'ErickSkrauch', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'elybydocs', 'Ely.by docs Documentation', + ['ErickSkrauch'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- 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 = [ + ('index', 'Elybydocs', 'Ely.by docs Documentation', + 'ErickSkrauch', 'Elybydocs', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/source/index.rst b/source/index.rst new file mode 100644 index 0000000..a76cfc4 --- /dev/null +++ b/source/index.rst @@ -0,0 +1,23 @@ +.. Ely.by docs documentation master file, created by + sphinx-quickstart on Sun Feb 1 22:04:01 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Добро пожаловать в документацию Ely.by! +======================================= + +В этой документации вы найдёте информацию о публичных сервисах проекта Ely.by, ознакомившись с которой вы сможете самостоятельно +реализовать свои программные продукты для совместной работы с сервисом Ely.by. + +Вы можете свободно улучшать и вносить предложения по изменениям в документацию в репозитории документации. + +Содержание: +~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + skin-system + minecraft-auth + oauth + diff --git a/source/minecraft-auth.rst b/source/minecraft-auth.rst new file mode 100644 index 0000000..340ead5 --- /dev/null +++ b/source/minecraft-auth.rst @@ -0,0 +1,304 @@ +Авторизация для Minecraft +------------------------- + +Здесь приведена информация по авторизации для лаунчеров и серверов Minecraft через сервис авторизации Ely.by. + +Протокол авторизации реализован максимально похожим на `оригинальный протокол авторизации Mojang `_, +но тем не менее эта документация описывает все доступные функции конкретно сервиса авторизации Ely.by. + +Общие положения +=============== + +* Все запросы должны выполняться на URL **http://minecraft.ely.by**. + +* При успешном запросе, сервер вернёт ответ со статусом 200. Любой другой код свидетельствует об ошибке. + +* Сервер всегда отвечает JSON данными, кроме случаев системных ошибок. Учитывайте это для отображения пользователю правильного + сообщения об ошибке. + +* В случае предусмотренной ошибки, вы получилите следующие данные: + + .. code-block:: javascript + + { + "error": "Краткое описание ошибки", + "errorMessage": "Более длинное описание ошибки на английском языке, пригодное для отображения пользователю." + } + +Предусмотренные ошибки +~~~~~~~~~~~~~~~~~~~~~~ + +В отличие от оригинального протокола, на Ely применяется меньший зоопарк ошибок + +.. list-table:: + :widths: 20 50 30 + :header-rows: 1 + + * - Ошибка (error) + - Причина + - Решение + * - Not Found + - Вы выполнили запрос на неизвестный URL или отправили POST запрос туда, где ожидался GET. + - Внимательно прочитайте документацию по запросу, который вы выполняете. + * - IllegalArgumentException + - Вы передали неполный список данных для выполнения запроса. + - Внимательно перепроверьте что вы шлёте в запросе и что указано в документации. + * - ForbiddenOperationException + - Пользователь ввёл/разработчик передал неверные значения. + - Необходимо вывести пользователю уведомление о неправильно введённых данных. + +Авторизация в лаунчере +====================== + +В этом разделе описана авторизация для лаунчера или любой другой настольной программы, которой необходимо получить +accessToken для игрового клиента Minecraft. Важно понимать, что этот accessToken не имеет ничего общего с accessToken, +получаемым при oAuth авторизации - это два абсолютно разных ключа. + +Все запросы выполняются на подуровень /auth POST запросом. + +.. function:: /auth/authenticate + + Непосредственная авторизация пользователя, используя его логин (ник или e-mail) и пароль. + + Входные параметры: + + :username: Никнейм пользователя или его e-mail (более предпочтительно). + + :password: Пароль пользователя. + + :clientToken: Уникальный токен лаунчера пользователя. + + Успешный ответ: + + .. code-block:: javascript + + { + 'accessToken': "Длинная_строка_содержащая_access_token", + 'clientToken': "Переданный_в_запросе_client_token", + 'availableProfiles': {}, /* См. ниже */ + 'selectedProfile': { + 'id': "Длинная_строка_с_uuid_пользователя", + 'name': "Текущий_nickname_пользователя", + 'legacy': false + } + } + + **availableProfiles** содержит в себе массив с одним элементом, таким же, как и selectedProfile. Добавлено только для + соответствия оригинальному протоколу и на деле не используется самими Mojang. + + Касательно параметра **legacy** в selectedProfile в оригинальном протоколе явно не даны пояснения на счёт этого + параметра, но сказано, что обычно он в false. Возможно, он как-то используется официальным лаунчером. + +.. function:: /auth/refresh + + Обновляет валидный accessToken. Этот запрос позволяет не хранить на клиенте его пароль, а оперировать только сохранённым + значением accessToken для практически бесконечной возможности проходить авторизацию. + + Входные параметры: + + :accessToken: Уникальный ключ, полученый после авторизации. + + :clientToken: Уникальный идентификатор клиента, относительно которого получен accessToken. + + .. note:: В оригинальном протоколе так же передаётся значение selectedProfile, но на деле от него мало что зависит и + для идентификации пользователя достаточно только этих двух параметров. Наш сервер не обидится, увидив его - + он просто его проигнорирует. + + В случае получения какой-либо предусмотренной ошибки, следует заново запросить пароль пользователя и произвести + обычную авторизацию. + + Успешный ответ: + + .. code-block:: javascript + + { + 'accessToken': "Новая_длинная_строка_ содержащая_access_token", + 'clientToken': "Переданный_в_запросе_client_token", + 'selectedProfile': { + 'id': "Длинная_строка_с_uuid_пользователя", + 'name': "Текущий_nickname_пользователя", + 'legacy': false + } + } + +.. function:: /auth/validate + + Этот запрос позволяет проверить валиден ли указанный accessToken или нет. Этот запрос не обновляет токен и его время + жизни, а только позволяет удостовериться, что он ещё действительный. + + Входные параметры: + + :accessToken: Уникальный ключ, полученый после авторизации. + + Успешным ответом будет являться любой результат, не содержащий в себе поля **error**. В `оригинальной документации + `_ не сказано, что в итоге должен вернуть этот запрос, так что ориентируйтесь + на поле **error** в теле ответа. + +.. function:: /auth/signout + + Не реализовано. + +.. function:: /auth/invalidate + + Не реализовано. + +Авторизация на сервере +====================== + +Эти запросы выполняются непосредственно клиентом и сервером при помощи внутреннего кода или библиотеки authlib +(начиная с версии 1.7.2). Они актуальны только в том случае, если вы уже произвели авторизацию и запустили игру с валидным +accessToken. Вам остаётся только заменить пути внутри игры/библиотеки на привидённые ниже пути. + +Поскольку непосредственно изменить что-либо в работе authlib или игры вы не можете, здесь не приводятся передаваемые значения +и ответы сервера. При необходимости вы сможете найти эту информацию самостоятельно в интернете. + +Через authlib +~~~~~~~~~~~~~ + +.. important:: Эта часть документации описывает запросы, выполняемые через authlib в версии игры 1.7.2+. Для более старых + версий смотрите раздел ниже. + +Все запросы из этой категории выполняются на подуровень /session. Перед каждым из запросов указан тип отправляемого запроса. + +.. function:: POST /session/join + + Запрос на этот URL производится клиентом в момент подключения к серверу с online-mode=true. + +.. function:: GET /session/hasJoined + + Запрос на этот URL выполняет сервер с online-mode=true после того, как клиент, пытающийся к нему подключится, успешно + выполнит join запрос. + + .. attention:: Внутри тела ответа есть параметр **properties**, который, в свою очередь, содержит поле **value** с + закодированной в ней base64 строкой. В оригинальной системе авторизации данные зашифрованы с помощью + приватного ключа и расшифровывались на клиенте с помощью публичного. + + Ely, в свою очередь, **не выполняет шифрацию вовсе**, поэтому вам необходимо отключить проверку подписи в + библиотеке authlib. В противном случае текстуры всегда будут признаваться невалидными. + +Для старых версий +~~~~~~~~~~~~~~~~~ + +.. important:: Эта часть документации описывает запросы, выполняемые более старыми версиями Minecraft, когда не применялась + библиотека authlib. Это все версии, младше версии 1.7.2. + +Все запросы из этой категории выполняются на подуровень /session/legacy. Перед каждым из запросов указан тип отправляемого запроса. + +Принцип обработки этих запросов такой же, как и для authlib, отличие только во входных параметрах и возвращаемых значения. + +.. function:: GET /session/legacy/join + + Запрос на этот URL производится клиентом в момент подключения к серверу с online-mode=true. + +.. function:: GET /session/legacy/hasJoined + + Запрос на этот URL выполняет сервер с online-mode=true после того, как клиент, пытающийся к нему подключится, успешно + выполнит join запрос. + +Важно не потерять GET параметр **?user=** в конце обоих запросов, чтобы получились следующие URL: +``http://minecraft.ely.by/session/legacy/hasJoined?user=``. + +Одиночная игра +============== + +По сути, одиночная игра - это локальный сервер, созданный для одного игрока. По крайней мере это так, начиная с версии 1.6, +в которой и был представлен механизм локальных серверов. + +Тем не менее, описанный ниже запрос актуален только для Minecraft 1.7.6+, когда для загрузки скинов стала использоваться +так же authlib. + +.. function:: GET /session/profile/{uuid} + + Запрос на этот URL выполняется клиентом в одиночной игре на локальном сервере (созданном посредством самой игры). + В URL передаётся UUID пользователя, с которым был запущен клиент, а в ответ получается информация о текстурах игрока. + +Готовые библиотеки authlib +========================== + +Поскольку самостоятельная реализация связана с трудностями поиска исходников, подключения зависимостей и в конце-концов с +процессом компиляции, ниже приведён список пропатченых библиотек со всеми необходимыми изменениями адресов, отключённой +проверкой подписи и встроенной системой скинов для серверов с online-mode=false. Вы можете использовать их "как есть". + +* Minecraft 1.8 - :download:`authlib 1.5.17 <_static/minecraft-auth/authlib/authlib-1.5.17.jar>` + +* Minecraft 1.7.10 - :download:`authlib 1.5.16 <_static/minecraft-auth/authlib/authlib-1.5.16.jar>` + +* Minecraft 1.7.9 - :download:`authlib 1.5.13 <_static/minecraft-auth/authlib/authlib-1.5.13.jar>` + +В более ранних версиях система скинов находилась внутри клиента, так что библиотеки ниже обеспечивают только авторизацию. + +* Minecraft 1.7.5 - :download:`authlib 1.3.1 <_static/minecraft-auth/authlib/authlib-1.3.1.jar>` + +* Minecraft 1.7.2 - :download:`authlib 1.3 <_static/minecraft-auth/authlib/authlib-1.3.jar>` + +.. hint:: На самом деле вам нужен только файл ``YggdrasilMinecraftSessionService.class``. Но здесь приведены готовые + библиотеки, чтобы вам не нужно было его искать и самостоятельно изменять. + +Для использования библиотеки вам необходимо заменить оригинальную, располагающуюся по пути /libraries/com/mojang/authlib/ +согласно её имени или же положить в другое место и просто при запуске игры подключить её, вместо оригинальной. + +Установка authlib на сервер +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Кроме этого библиотеку необходимо установить и на сервер. Для этого вам понадобится файл сервера с расширением .jar. +Щёлкните на нём правой кнопкой мыши, выберите вариант "Открыть с помощью..." и выберите удобный архиватор (скорее всего WinRar). +Затем проделайте те же действия с authlib такой же версии, что и ваш сервер. + +Перед вами будет 2 окна: одно с файлами authlib, другое с файлами сервера. Вам необходимо перетащить **только папку "com"** +из authlib на сервер и подтвердить замену. + +.. figure:: _static/minecraft-auth/authlib-install.png + :align: center + :alt: Процесс перетягивания: что куда. + +После этих действий вы можете закрыть оба окна и в настройках сервера включить online-mode=true, авторизация через Ely.by +установлена и работает! + +Установка на версии ниже 1.7.2 +============================== + +Для более старых версий существует достаточно большое многообразие различных случаев, раскрыть которые в этой документации +не представляется возможным. Вся установка заключается в замене определённых строк в определённых классах через +InClassTranslator. + +На форуме RuBukkit есть отличный пост, в котором собрана вся нужна информация по именам классов на различных версиях +Minecraft. Переписывать его сюда не имеет смысла, так что просто перейдите на его страницу и найдите нужную версию. + +|rubukkit_link|. + +.. |rubukkit_link| raw:: html + + RuBukkit - + Список классов и клиентов для MCP + +Пример установки +~~~~~~~~~~~~~~~~ + +Предположим, что вы хотите установить авторизацию на сервер версии 1.5.2. + +Сначала вы переходите по вышепривидённой ссылке, выбираете нужную версию (1.5.2) и видите список классов: + +* **bdk.class** - путь до joinserver + +* **jg.class** - путь до checkserver + +Затем вы должны взять .jar файл клиента и открыть его любым архиватором. После чего вам необходимо найти файл **bdk.class**. +Для этого удобно воспользоваться поиском. + +После того, как вы нашли файл, его нужно извлечь из архива - просто перетащите его оттуда в удобную для вас дирикторию. + +Дальше запустите InClassTranslator и в нём откройте этот класс. Слева будет список найденных в файле строк, которые вы +можете изменить. Нужно заменить только строку, отвечающую за запрос на подключение к серверу: + +.. figure:: _static/minecraft-auth/installing_by_inclasstranslator.png + :align: center + :alt: Процесс перетягивания: что куда. + +После этого вам нужно положить изменённый .class обратно в .jar файл игры. + +Ту же самую операцию вам необходимо провести и с сервером, только заменить ссылку на hasJoined. + +----------------------- + +После этих действий вам нужно в настройках включить online-mode=true и сервер станет пускать на себя только тех игроков, +которые будут авторизованы через Ely.by. \ No newline at end of file diff --git a/source/oauth.rst b/source/oauth.rst new file mode 100644 index 0000000..03b7c55 --- /dev/null +++ b/source/oauth.rst @@ -0,0 +1,285 @@ +oAuth авторизация +----------------- + +На этой странице вы найдёте информацию о подключении oAuth авторизации для вашего сайта через сервис Ely.by. +Это такой же способ авторизации, как и вход через Вконтакте, Twitter, Google, Facebook и другие. +Вкупе с использованием нашей системы скинов на своём сервере это позволит увеличить количество игроков на сервере и на сайте сервера. + +Добавление приложения +===================== + +Для начала вам необходимо создать новое приложение. Вы можете это сделать на `Странице добавления приложения `_. +Внимательно отнеситесь к заполняемым полям - они будут влиять на внешний вид страницы авторизации. + +Описание: +~~~~~~~~~ + +:Название: Задаёт имя приложения, отображаемое на странице авторизации и в списке ваших приложений. **Обязательное поле**. + +:Описание: Отображается под назаванием приложения и позволяет пользователю убедится в том, что он авторизуется именно на желаемом ресурсе. + +:Адрес сайта: Позволяет задать обратную ссылку на ваш сайт. + +:Изображение: Ссылка на логотип или нечто иное, идентифицирующее ваш проект. Это поле не обязательно, но является крайне желательным для заполнения. + +Параметры авторизации: +~~~~~~~~~~~~~~~~~~~~~~ + +:Тип ответа: Задаёт дальнейшие действия сервиса oAuth авторизации после выполнения пользователем авторизации. + На данным момент поддерживается только вариант "Получить код авторизации", что является форматом ответа для авторизации на сайтах. + +:Перенаправление: URL адрес, на который будет переадресован пользователь с данными, согласно выбранному *типу ответа*, + после авторизации. **Обязательное поле**. + +Разрешения: +~~~~~~~~~~~ + +.. note:: Поскольку API для работы с Ely.by ещё не создано, вместе с получением токена доступа (access_token) вы получите и данные о пользователе. + +.. list-table:: Список доступных разрешений + :widths: 15 85 + :header-rows: 1 + + * - Разрешение + - Описание + * - E-mail адрес + - Регистрационный e-mail адрес пользователя, подтверждённый им при регистрации. + +Инициализация авторизации +========================= + +После того, как вы добавите приложение, получите ссылку на инициализацию авторизации и разместите её в любом удобном месте, например так: + +.. code-block:: html + + Войти через Ely.by + +По нажатию на ссылку, `если всё в порядке `_, пользователь попадёт на нашу страницу авторизации, где будут представлены данные вашего приложения, +указанные при его регистрации. + +После успешного завершения процедуры авторизации, пользователь будет перенаправлен на страницу **перенаправления после авторизации** (redirect_uri). + +Если пользователь откажется от авторизации, то вы можете обработать и это, согласно `следующему разделу `_. + +Данные придут в следующем формате: + +.. code-block:: html + + ?code=<код_авторизации> + +Например это может выглядеть так: + +.. code-block:: http + + http://someresource.by/oauth/ely.php?code=dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ + +Где: + +.. list-table:: + :widths: 15 85 + :header-rows: 0 + + * - redirect_uri + - http://someresource.by/oauth/ely.php + * - код_авторизации + - dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ + +Обмен кода на ключ +================== + +После получения кода авторизации, вам необходимо обменять его на ключ авторизации (access_key). Для этого вам необходимо выполнить POST запрос на url: + +.. code-block:: http + + http://oauth.ely.by/access-token + +И передать туда параметры **client_id**, **client_secret**, **redirect_uri** и **grant_type**. Значения этих параметров +вы можете найти на странице с информацией о вашем приложении. + +Пример реализации запроса на PHP: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: php + + 'BdBrINDm3CMXhrb6gaAeWqquyZmP2VUS9CLDU50M', // Публичный ключ + 'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Секретный ключ + 'redirect_uri' => 'http://someresource.by/oauth/some.php', // Редирект после авторизации + 'grant_type' => 'authorization_code' // Просто нужно по протоколу. Не меняйте это значение + ); + + // Выполняем код ниже только если пришёл код авторизации + if (!is_null($_GET['code'])) { + $oauth_params['code'] = $_GET['code']; + + $curl = curl_init(); + curl_setopt($curl, CURLOPT_URL, 'http://oauth.ely.by/access-token'); + curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); + curl_setopt($curl, CURLOPT_POST, true); + curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($oauth_params)); + $out = json_decode(curl_exec($curl)); + curl_close($curl); + } + +Пояснение по коду: + +* Сначала мы объявляем переменную $oauth_params, в которую заносим значения, полученные после регистрации приложения. + +* Затем проверяем, пришёл ли код. Если кода нет, то, вероятно, пользователь отклонил запрошенные права. Подробнее об ошибках. + +* Инициализируем Curl для отправки запроса на форму обмена кода на токен: http://oauth.ely.by/access-token. + +* Запрос должен быть выполнен как POST и в него должны быть переданы 5 параметров: client_id, client_secret, redirect_uri, grant_type и code. + Имена полей должны быть именно такими, порядок не важен. + +* Выполняем запрос, получаем строку ответа от Ely и сразу же декодируем JSON строку. + +------------------- + +Таким образом в переменной **$out** будет находиться информация об авторизации. + +Ответ от сервера +================ + +В случае успешного запроса, в теле ответа будет находиться результат обмена кода авторизации на токен доступа. +Данные являются простым JSON объектом и могут быть прочитаны в большинстве языков программирования без привлечения сторонних библиотек. + +Ознакомьтесь со списком возможных ошибкок в `следующем разделе `_. + +------------------- + +После парсинга JSON строки вы получите следующие данные: + +.. code-block:: javascript + + { + "access_token": "4qlktsEiwgspKEAotazem0APA99Ee7E6jNryVBrZ", /* Токен доступа */ + "token_type": "Bearer", + "expires": 1407528497, /* Unix-timestamp истечения токена доступа */ + "expires_in": 86400, /* Количество секунд, на которое выдан токен */ + "user_data": { + "id": "1", /* Уникальный id пользователя */ + "nickname": "ErickSkrauch", /* Текущий ник пользователя */ + "profileUrl": "http://ely.by/erickskrauch", /* Ссылка на профиль */ + "email": "erickskrauch@ely.by", /* Вы получите E-mail только если вы запросили право на доступ */ + "skin": { /* Ссылки на различные изображения скина пользователя */ + "faceUrl": "http://ely.by/minecraft/skin_buffer/faces/1c659e89546ae0cbf16965619053e31d.png", + "renderUrl": "http://ely.by/minecraft/skin_buffer/skins/1c659e89546ae0cbf16965619053e31d.png", + "skinUrl": "http://ely.by/minecraft/skins/1c659e89546ae0cbf16965619053e31d.png" + } + } + } + +На этом процедура авторизации закончена. Дальнейшая обработка данных зависит от потребностей вашего приложения. +Вы можете выдать пользователю форму для довведения дополнительных данных или сразу произвести его регистрацию +в своей системе и дальнейшую авторизацию. + +Возможные ошибки +================ + +Так или инчае, но реализовать oAuth авторизацию с первого раза получается далеко не у всех. Самым важным является правильно +понять причину и исправить её. Ниже приведены стандартные и предусмотренные сообщения, которые вы можете получить в случае +неправильной передачи данных на сервер или нестандартных действий пользователя. + +Тем не менее, если вы получили ошибку, неописанную в этой документации, пожалуйста, сообщите мне о ней в +`форму обратной связи `_. + +.. _auth-start: + +Ошибки при инициализации авторизации +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _auth-start-fields: + +Поля +"""" + +Ошибка с текстом: + +.. code-block:: text + + The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "redirect_uri" parameter. + +Означает то, что вы забыли передать в параметрах то или иное значение. +Необходимое значение указано во 2 предложении. +Чтобы решить эту проблему вам нужно просто добавить поле и его значение в передаваемые параметры. + +Клиент +"""""" + +Если же вы встретили следующую проблему: + +.. code-block:: text + + Client authentication failed. + +Это означает, что переданные параметры не соответствуют ни одному зарегистрированному приложению. +Проверьте ваши значения code и redirect_uri, а лучше используйте уже сгенерированную ссылку на странице информации о приложении. + +.. _auth-finish: + +Ошибки во время завершения авторизации +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +После того, как пользователь пройдёт авторизацию на Ely, ему будет предоставлен список разрешений, касающихся вашего приложения. +Если пользователь разрешит доступ, то всё пройдёт как описано в документации выше, но если же он нажмёт на кнопку "Отказать", +то он будет перенаправлен на ваш redirect_uri, но с другими GET параметрами: + +.. code-block:: http + + http://someresource.by/oauth/some.php?error=access_denied&error_message=The+resource+owner+or+authorization+server+denied+the+request. + +То есть в вашем обработчике по пути redirect_uri вам необходимо обработать состояние, когда нет параметра code, но есть error +и вывести пользователю какое-либо сообщение о том, что пользователь не дал доступа к своим данным - вы не дадите доступа к своему сервису :_: + +.. _access-token: + +Ошибки во время обмена токенов +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Поскольку обмен кода на токен доступа происходит через отправку POST запроса, данные передаются обратно в формате JSON. +Поэтому опознать сообщение об ошибке можно по наличию поля **error** в ответе от сервера. + +В случае возникновения ошибки вы получите 2 поля: + +.. code-block:: javascript + + { + "error": "invalid_request", + "error_description": "bla bla bla bla" + } + +В поле **error** находится системное описание ошибки, оно указано в скобках у разделов ниже. В поле **error_description** +находится описание ошибки на английском языке. Содержание достаточно для самостоятельного решения проблемы, но в случае непонятности +той или иной ошибки, внизу привидён список возможных ошибок с пояснениями на русском языке. + +Поля (invalid_request) +"""""""""""""""""""""" + +Смотрите "Ошибки при инициализации авторизации - :ref:`auth-start-fields`". + +Неподдерживаемый Grant (unsupported_grant_type) +""""""""""""""""""""""""""""""""""""""""""""""" + +Если вы встретили эту ошибку, то это значит, что вы попытались произвести авторизацию по неизвестному для нашего oAuth сервера типу Grant. +На данный момент Ely поддерживает только grant **authorization_code**, поэтому использование любого другого значения привидёт к этой ошибке. + +Клиент (invalid_client) +""""""""""""""""""""""" + +Эта ошибка возникает в случае, когда трио значений **client_id**, **client_secret** и **redirect_uri** не совпали +ни с одним из зарегистрированных приложений. Перепроверьте ваши значения. + +Ошибка доступа (invalid_grant) +"""""""""""""""""""""""""""""" + +Эта ошибка встречается в том случае, если переданный **code** не соответствует вашим **client_id** и **redirect_uri**. +Возможно, вы неправильно обработали полученные данные или на нашем сервере были сброшены коды авторизации по каким-либо техническим причинам (маловероятно). + +Неизвестная ошибка (undefined_error) +"""""""""""""""""""""""""""""""""""" + +Код на сервере никогда не будет идеален и может случится так, что виноват буду я, а не вы. Если вы стабильно получаете эту ошибку, +то, пожалуйста, сообщите мне об этом в `форму обратной связи `_, чтобы я мог оперативно всё исправить. diff --git a/source/skin-system.rst b/source/skin-system.rst new file mode 100644 index 0000000..8054152 --- /dev/null +++ b/source/skin-system.rst @@ -0,0 +1,163 @@ +Система скинов +-------------- + +На этой странице вы найдёте информацию о самостоятельной реализации системы скинов на базе сервиса Ely.by. + +Система скинов Ely.by, в отличие от других, не заменяет, а дополняет официальную, тем самым игроки с лицензией не теряют +свои скины, а игроки без лицензии смогут установить себе скин и видеть скины других игроков. + +Кроме того, в основных принципах сервиса лежит соответствие официальной системе скинов: нет плащей, нет ушек, нет HD-скинов. +Это означает, что на вашем сервере не будут бегать разноцветные пугала с вырвиглазными скинами. + +URL-адреса запросов +=================== + +Система скинов располагается по URL **http://skinsystem.ely.by**. На сервере доступно 3 основных обработчика: + +.. function:: /skins/{nickname}.png + + Этот URL отвечает за загрузку скинов. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить. + +.. function:: /cloaks/{nickname}.png + + Этот URL отвечает за загрузку плащей. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить. + + Хотя Ely.by не поддерживает пользовательскую загрузку плащей, мы оставляем за собой право устанавливать дополнительные, + относительно официальной системы скинов, плащи. В любом случае, мы будет пользоваться теми же принципами, что и Mojang - + плащи только за великие заслуги. + +.. function:: /textures/{nickname} + + По этому URL вы можете получить текстуры для указанного в запросе **nickname**. Результатом является JSON строка, с + meta-информацией о скине следующего формата: + + .. code-block:: javascript + + { + 'SKIN': { + 'url': 'http://example.com/skin.png', + 'hash': 'uniquehashofskin', + 'metadata': { + 'model': 'default' /* default или slim, в зависимости от формата скина */ + } + }, + 'CAPE': { + 'url': '', + 'hash': '' + } + } + + *В абсолютном большинстве случаев, содержание CAPE будет именно таким, как показано выше.* + +.. note:: Ник не чувствителен к регистру и внутри обработчика в любом случае приводится к нижнему регистру. + +Кроме того, для всех запросов необходимо в GET параметрах передать следующие значения: + +:version: Версия протокола, по которому идёт запрос на скины. На данный момент таковым является 2 протокол, т.е. вам + нужно всегда указывать version=2. + +:minecraft_version: Версия Minecraft, с которой идёт запрос. Этот параметр можно не передавать в том случае, если вы + передаёте параметр authlib_version. + +:authlib_version: Версия authlib, с которой выполняется запрос. Этот параметр актуален для версий Minecraft 1.7.6+, когда + для загрузки скинов стала использоваться отдельная библиотека, а не реализация внутри игры. + + Параметр может быть передан вместо параметра **minecraft_version**. + +Если в запросе не будет параметра **version** и **minecraft_version** или **authlib_version**, сервер ответит 400 +ошибкой и скин не будет загружен. + +Примеры запросов +~~~~~~~~~~~~~~~~ + +.. code-block:: http + + http://skinsystem.ely.by/skins/erickskrauch.png?version=2&minecraft_version=1.7.2 + +Получает скин игрока **erickskrauch** с версии Minecraft 1.7.2. + +.. code-block:: http + + http://skinsystem.ely.by/cloaks/notch?version=2&minecraft_version=1.6.4 + +Получает плащ игрока **notch** с версии Minecraft 1.6.4. Обратите внимание, что расширение ".png" не передано. + +.. code-block:: http + + http://skinsystem.ely.by/textures/EnoTiK?version=2&authlib_version=1.5.17 + +Получает текстуры игрока **EnoTiK** с версии authlib 1.5.17 (версия Minecraft 1.8). + +Вспомогательные адреса запросов +=============================== + +Кроме того, во 2 версии протокола системы скинов определены несколько специальных URL, которые проксируют трафик внутрь +основных запросов, перечисленных выше. + +Ник как GET параметр +~~~~~~~~~~~~~~~~~~~~ + +Эти URL, в отличие от основных запросов, позволяют передать ник игрока в качестве одного из GET параметров. Такие запросы +полезены для версии Minecraft 1.5.2 и ниже, когда внутри кода игры не использовалась подстановка %s для ника, а производилась +простая конкатенация строк. Таким образом можно передать все необходимые GET параметры, указав ник последним. + +.. function:: /skins/?name={nickname}.png + + Тот же запрос на скин. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить. + +.. function:: /cloaks/?name={nickname}.png + + Тот же запрос на плащ. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить. + +Примеры запросов: +""""""""""""""""" + +.. code-block:: http + + http://skinsystem.ely.by/skins/?version=2&minecraft_version=1.5.2&name=erickskrauch.png + +Получает скин игрока **erickskrauch** с версии Minecraft 1.5.2. + +.. code-block:: http + + http://skinsystem.ely.by/cloaks/?version=2&minecraft_version=1.4.7&name=notch + +Получает плащ игрока **notch** с версии Minecraft 1.4.7. Обратите внимание, что расширение ".png" не передано. + +Старый формат запроса +~~~~~~~~~~~~~~~~~~~~~ + +В 1 версии протокола системы скинов применялся другой способ загрузки скинов. Все запросы шли по URL +**http://ely.by/minecraft.php** и все данные передавались через GET параметры. + +На данный момент любой запрос, выполненный на вышеуказанный URL приведёт к 301 редиректу на +**http://skinsystem.ely.by/minecraft.php**, где запрос будет проксирован на основные запросы. + +Этот запрос является fallback роутом, применяемым для обратной совместимости с 1 версией и не рекомендуется для +использования в новых проектах. Тем не менее, он должен быть описан, так как применятся и будет достаточно долго применяться +в связи с долгосрочным переходом на 2 версию протокола системы скинов. + +1 версия системы скинов (deprecated) +==================================== + +.. warning:: Информация в этом разделе является устаревшей и приведена здесь только ради создания иллюзии крутого развития + проекта. В любом случае вы **не должны** использовать этот протокол, т.к. в один момент он окончательно перестанет + работать. + +На старте проекта применялся URL для загрузки скинов **http://ely.by/minecraft.php**, в который через GET параметры +передавались данные. Сейчас этот URL является устаревшим и планомерно выводится из обращения в пользу 2 версии протокола. + +.. function:: /minecraft.php + + Параметры, передаваемые в этот запрос: + + :name: Имя игрока без учёта регистра и без расширения **.png**. + + :type: Тип запрашиваемых данных. Возможные значения: skin и cloack. Изначально была допущена ошибка, из-за которой + запрос на плащи шёл с значением cloack, вместо cloak. Увы, это так и останется в истории проекта. + + :mine_ver: Версия Minecraft. Точки в версии должны были быть заменены на прочерки, т.е. 1.7.2 должно было быть передано + как 1_7_2. Хотя могло работать и с точками :) + + :ver: Версия протокола. Обычно передавалось значение 1_0_0, которое, в принципе, ни на что не влияло, но тем не менее + передавалось. Сейчас применяется для идентификации запроса, проксируемого с 1 версии во 2.