mirror of
https://github.com/elyby/docs.git
synced 2024-12-27 07:20:29 +05:30
Initial commit
This commit is contained in:
ErickSkrauch
commit
d14624f7ed
5
.gitignore
vendored
Normal file
5
.gitignore
vendored
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
### My idea folder
|
||||||
|
/.idea
|
||||||
|
|
||||||
|
### BUILD FOLDER
|
||||||
|
/build
|
||||||
177
Makefile
Normal file
177
Makefile
Normal file
@ -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 <target>' where <target> 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."
|
||||||
242
make.bat
Normal file
242
make.bat
Normal file
@ -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 ^<target^>` where ^<target^> 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
|
||||||
BIN
source/_static/favicon.ico
Normal file
BIN
source/_static/favicon.ico
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 198 B |
BIN
source/_static/minecraft-auth/authlib-install.png
Normal file
BIN
source/_static/minecraft-auth/authlib-install.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
BIN
source/_static/minecraft-auth/authlib/authlib-1.3.1.jar
Normal file
BIN
source/_static/minecraft-auth/authlib/authlib-1.3.1.jar
Normal file
Binary file not shown.
BIN
source/_static/minecraft-auth/authlib/authlib-1.3.jar
Normal file
BIN
source/_static/minecraft-auth/authlib/authlib-1.3.jar
Normal file
Binary file not shown.
BIN
source/_static/minecraft-auth/authlib/authlib-1.5.13.jar
Normal file
BIN
source/_static/minecraft-auth/authlib/authlib-1.5.13.jar
Normal file
Binary file not shown.
BIN
source/_static/minecraft-auth/authlib/authlib-1.5.16.jar
Normal file
BIN
source/_static/minecraft-auth/authlib/authlib-1.5.16.jar
Normal file
Binary file not shown.
BIN
source/_static/minecraft-auth/authlib/authlib-1.5.17.jar
Normal file
BIN
source/_static/minecraft-auth/authlib/authlib-1.5.17.jar
Normal file
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
28
source/_static/style.css
Normal file
28
source/_static/style.css
Normal file
@ -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;
|
||||||
|
}
|
||||||
5
source/_templates/layout.html
Normal file
5
source/_templates/layout.html
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
{# layout.html #}
|
||||||
|
{# Import the theme's layout. #}
|
||||||
|
{% extends "!layout.html" %}
|
||||||
|
|
||||||
|
{% set css_files = css_files + ['_static/style.css'] %}
|
||||||
260
source/conf.py
Normal file
260
source/conf.py
Normal file
@ -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
|
||||||
|
# "<project> v<release> 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 <link> 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
|
||||||
23
source/index.rst
Normal file
23
source/index.rst
Normal file
@ -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
|
||||||
|
|
||||||
304
source/minecraft-auth.rst
Normal file
304
source/minecraft-auth.rst
Normal file
@ -0,0 +1,304 @@
|
|||||||
|
Авторизация для Minecraft
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
Здесь приведена информация по авторизации для лаунчеров и серверов Minecraft через сервис авторизации Ely.by.
|
||||||
|
|
||||||
|
Протокол авторизации реализован максимально похожим на `оригинальный протокол авторизации Mojang <http://wiki.vg/Authentication>`_,
|
||||||
|
но тем не менее эта документация описывает все доступные функции конкретно сервиса авторизации 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**. В `оригинальной документации
|
||||||
|
<http://wiki.vg/Authentication#Validate>`_ не сказано, что в итоге должен вернуть этот запрос, так что ориентируйтесь
|
||||||
|
на поле **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
|
||||||
|
|
||||||
|
<a href="http://www.rubukkit.org/threads/spisok-klassov-i-klientov-dlja-mcp.25108/#post-303710" target="_blank">RuBukkit -
|
||||||
|
Список классов и клиентов для MCP</a>
|
||||||
|
|
||||||
|
Пример установки
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Предположим, что вы хотите установить авторизацию на сервер версии 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.
|
||||||
285
source/oauth.rst
Normal file
285
source/oauth.rst
Normal file
@ -0,0 +1,285 @@
|
|||||||
|
oAuth авторизация
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
На этой странице вы найдёте информацию о подключении oAuth авторизации для вашего сайта через сервис Ely.by.
|
||||||
|
Это такой же способ авторизации, как и вход через Вконтакте, Twitter, Google, Facebook и другие.
|
||||||
|
Вкупе с использованием нашей системы скинов на своём сервере это позволит увеличить количество игроков на сервере и на сайте сервера.
|
||||||
|
|
||||||
|
Добавление приложения
|
||||||
|
=====================
|
||||||
|
|
||||||
|
Для начала вам необходимо создать новое приложение. Вы можете это сделать на `Странице добавления приложения <http://ely.by/auth/add>`_.
|
||||||
|
Внимательно отнеситесь к заполняемым полям - они будут влиять на внешний вид страницы авторизации.
|
||||||
|
|
||||||
|
Описание:
|
||||||
|
~~~~~~~~~
|
||||||
|
|
||||||
|
:Название: Задаёт имя приложения, отображаемое на странице авторизации и в списке ваших приложений. **Обязательное поле**.
|
||||||
|
|
||||||
|
:Описание: Отображается под назаванием приложения и позволяет пользователю убедится в том, что он авторизуется именно на желаемом ресурсе.
|
||||||
|
|
||||||
|
:Адрес сайта: Позволяет задать обратную ссылку на ваш сайт.
|
||||||
|
|
||||||
|
:Изображение: Ссылка на логотип или нечто иное, идентифицирующее ваш проект. Это поле не обязательно, но является крайне желательным для заполнения.
|
||||||
|
|
||||||
|
Параметры авторизации:
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
:Тип ответа: Задаёт дальнейшие действия сервиса oAuth авторизации после выполнения пользователем авторизации.
|
||||||
|
На данным момент поддерживается только вариант "Получить код авторизации", что является форматом ответа для авторизации на сайтах.
|
||||||
|
|
||||||
|
:Перенаправление: URL адрес, на который будет переадресован пользователь с данными, согласно выбранному *типу ответа*,
|
||||||
|
после авторизации. **Обязательное поле**.
|
||||||
|
|
||||||
|
Разрешения:
|
||||||
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. note:: Поскольку API для работы с Ely.by ещё не создано, вместе с получением токена доступа (access_token) вы получите и данные о пользователе.
|
||||||
|
|
||||||
|
.. list-table:: Список доступных разрешений
|
||||||
|
:widths: 15 85
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Разрешение
|
||||||
|
- Описание
|
||||||
|
* - E-mail адрес
|
||||||
|
- Регистрационный e-mail адрес пользователя, подтверждённый им при регистрации.
|
||||||
|
|
||||||
|
Инициализация авторизации
|
||||||
|
=========================
|
||||||
|
|
||||||
|
После того, как вы добавите приложение, получите ссылку на инициализацию авторизации и разместите её в любом удобном месте, например так:
|
||||||
|
|
||||||
|
.. code-block:: html
|
||||||
|
|
||||||
|
<a href="<ваша_ссылка>">Войти через Ely.by</a>
|
||||||
|
|
||||||
|
По нажатию на ссылку, `если всё в порядке </oauth.html#auth-start>`_, пользователь попадёт на нашу страницу авторизации, где будут представлены данные вашего приложения,
|
||||||
|
указанные при его регистрации.
|
||||||
|
|
||||||
|
После успешного завершения процедуры авторизации, пользователь будет перенаправлен на страницу **перенаправления после авторизации** (redirect_uri).
|
||||||
|
|
||||||
|
Если пользователь откажется от авторизации, то вы можете обработать и это, согласно `следующему разделу </oauth.html#auth-finish>`_.
|
||||||
|
|
||||||
|
Данные придут в следующем формате:
|
||||||
|
|
||||||
|
.. code-block:: html
|
||||||
|
|
||||||
|
<redirect_uri>?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
|
||||||
|
|
||||||
|
<?php
|
||||||
|
// В этой переменной будут храниться ваши параметры oAuth
|
||||||
|
$oauth_params = array(
|
||||||
|
'client_id' => '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 объектом и могут быть прочитаны в большинстве языков программирования без привлечения сторонних библиотек.
|
||||||
|
|
||||||
|
Ознакомьтесь со списком возможных ошибкок в `следующем разделе </oauth.html#access-token>`_.
|
||||||
|
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
После парсинга 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 авторизацию с первого раза получается далеко не у всех. Самым важным является правильно
|
||||||
|
понять причину и исправить её. Ниже приведены стандартные и предусмотренные сообщения, которые вы можете получить в случае
|
||||||
|
неправильной передачи данных на сервер или нестандартных действий пользователя.
|
||||||
|
|
||||||
|
Тем не менее, если вы получили ошибку, неописанную в этой документации, пожалуйста, сообщите мне о ней в
|
||||||
|
`форму обратной связи <http://ely.by/site/contact>`_.
|
||||||
|
|
||||||
|
.. _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)
|
||||||
|
""""""""""""""""""""""""""""""""""""
|
||||||
|
|
||||||
|
Код на сервере никогда не будет идеален и может случится так, что виноват буду я, а не вы. Если вы стабильно получаете эту ошибку,
|
||||||
|
то, пожалуйста, сообщите мне об этом в `форму обратной связи <http://ely.by/site/contact>`_, чтобы я мог оперативно всё исправить.
|
||||||
163
source/skin-system.rst
Normal file
163
source/skin-system.rst
Normal file
@ -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.
|
||||||
Loading…
Reference in New Issue
Block a user