Removed the superfluous reST build system in docs/sphinx. ReadTheDoc-style rst files are produced using tools directly in the wiki repo now instead.
This commit is contained in:
Griatch
parent
399f896b03
commit
2306449ee1
81 changed files with 359 additions and 16545 deletions
119
docs/README.txt
119
docs/README.txt
|
|
@ -1,14 +1,19 @@
|
|||
|
||||
===========
|
||||
DOCS README
|
||||
===========
|
||||
|
||||
* Evennia docs and manual
|
||||
EVENNIA DOCUMENTATION
|
||||
=====================
|
||||
|
||||
- The most updated documentation is found in the online wiki,
|
||||
|
||||
http://code.google.com/p/evennia/wiki/Index
|
||||
|
||||
- Evennia is extensively documented. Our manual is the
|
||||
continuously updating online wiki,
|
||||
|
||||
https://github.com/evennia/evennia/wiki
|
||||
|
||||
- Snapshots of the manual are also mirrored in reST
|
||||
form to ReadTheDocs:
|
||||
|
||||
http://evennia.readthedocs.org/en/latest/
|
||||
|
||||
- You can also ask for help from the evennia community,
|
||||
|
||||
http://groups.google.com/group/evennia
|
||||
|
|
@ -17,45 +22,11 @@ DOCS README
|
|||
|
||||
#evennia on the Freenode network
|
||||
|
||||
|
||||
------------------------
|
||||
* Sphinx Manuals
|
||||
------------------------
|
||||
|
||||
The folder docs/sphinx contains a source tree with Evennia's online wiki
|
||||
formatted into reStructuredText for easy (and good looking!) offline
|
||||
browsing or printing.
|
||||
|
||||
To build the sources you need to install Sphinx. Linux users can get it
|
||||
through their package managers (in Debian it's called python-sphinx). Or
|
||||
you can download it here:
|
||||
|
||||
http://sphinx.pocoo.org/index.html
|
||||
|
||||
Go into docs/sphinx and run
|
||||
|
||||
make html
|
||||
|
||||
You will see a lot of output (and probably some errors too, Evennia's docs
|
||||
are not formatted to reST format by default). When done, point your
|
||||
web browser to docs/sphinx/build/html/index.html to see the nice manual.
|
||||
|
||||
If you don't want html output, you can output to a host of other formats,
|
||||
use just "make" for a list of options.
|
||||
|
||||
|
||||
Note: In docs/sphinx are two more dirs, wiki2rest and src2rest. These
|
||||
can be used to create reST-formatted documentation from raw sources.
|
||||
They depend on a host of external libraries however, so best stay away
|
||||
from them unless you are an Evennia dev. Read the headers of the
|
||||
respective *.py files for instructions.
|
||||
|
||||
|
||||
-------------------
|
||||
* Doxygen auto-docs
|
||||
-------------------
|
||||
|
||||
In docs/doxygen you can build the developer auto-docs
|
||||
You can build the developer auto-docs
|
||||
(a fancy searchable index of the entire source tree).
|
||||
This makes use of doxygen, a doc generator that parses
|
||||
the source tree and creates docs on the fly.
|
||||
|
|
@ -63,12 +34,14 @@ DOCS README
|
|||
- Install doxygen (v1.7+)
|
||||
|
||||
Doxygen is available for most platforms from
|
||||
|
||||
http://www.stack.nl/~dimitri/doxygen/
|
||||
|
||||
or through your package manager in Linux.
|
||||
|
||||
- Run
|
||||
|
||||
> doxygen config.dox
|
||||
doxygen config.dox
|
||||
|
||||
This will create the auto-docs in a folder 'doxygen/html'.
|
||||
|
||||
|
|
@ -82,12 +55,62 @@ DOCS README
|
|||
will be created with the latex sources. With the latex
|
||||
processing system installed, then run
|
||||
|
||||
> make
|
||||
make
|
||||
|
||||
in the newly created folder to create the pdf. Be warned
|
||||
however that the pdf docs are >340 pages long!
|
||||
|
||||
- Doxyfile is lavishly documented and allows for plenty of
|
||||
configuration to get the docs to look the way you want.
|
||||
You can also output to other formats suitable for various
|
||||
developer environments, Windows help files etc.
|
||||
- Doxyfile is allows for plenty of configuration to get the
|
||||
docs to look the way you want. You can also output to other
|
||||
formats suitable for various developer environments, Windows
|
||||
help files etc.
|
||||
|
||||
------------------------
|
||||
* Sphinx Manuals
|
||||
------------------------
|
||||
|
||||
If you want to build the reST manuals yourself, you basically need to
|
||||
convert the wiki. First place yourself in a location where you want
|
||||
to clone the wiki repo to, then clone it:
|
||||
|
||||
git clone https://github.com/evennia/evennia.wiki.git
|
||||
|
||||
- Enter this directory and check out the sphinx branch:
|
||||
|
||||
git checkout sphinx
|
||||
|
||||
This branch has, apart from all the wiki pages (*.md files), also has a
|
||||
an extra directory sphinx/ that will hold the converted data.
|
||||
|
||||
- You need Pandoc for the markdown-to-reST conversion:
|
||||
|
||||
http://johnmacfarlane.net/pandoc/installing.html
|
||||
|
||||
You need a rather recent version. The versions coming with some linux
|
||||
repos are too old to support "github-flavoured markdown" conversion.
|
||||
See that page for getting the Haskill build environment in that case.
|
||||
|
||||
- You also need sphinx,
|
||||
|
||||
http://sphinx-doc.org/
|
||||
|
||||
You can most likely get it with 'pip install sphinx' under Linux.
|
||||
|
||||
- With all this in place, go to the pylib/ folder and run the
|
||||
converter script:
|
||||
|
||||
python update_rest_docs.py
|
||||
|
||||
If all goes well, you will see all the wiki pages getting converted.
|
||||
The converted *.rst files will end up in the sphinx/ directory.
|
||||
|
||||
- Finally, go to sphinx/ and run
|
||||
|
||||
make html
|
||||
|
||||
If sphinx is installed, this will create the html files in
|
||||
sphinx/.build. To look at them, point your browser to
|
||||
|
||||
<path-to-wiki-repo>/sphinx/.build/index.html
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue