From: Radek Czajka Date: Wed, 4 Apr 2012 14:06:10 +0000 (+0200) Subject: some basic docs X-Git-Url: https://git.mdrn.pl/wolnelektury.git/commitdiff_plain/78c155d16f5e0a16288479a4259d972fd94e6a3f some basic docs --- diff --git a/apps/catalogue/models.py b/apps/catalogue/models.py index a49c1e5cd..29106b184 100644 --- a/apps/catalogue/models.py +++ b/apps/catalogue/models.py @@ -53,6 +53,10 @@ class TagSubcategoryManager(models.Manager): class Tag(TagBase): + """A tag attachable to books and fragments (and possibly anything). + + Used to represent searchable metadata (authors, epochs, genres, kinds), + fragment themes (motifs) and some book hierarchy related kludges.""" name = models.CharField(_('name'), max_length=50, db_index=True) slug = models.SlugField(_('slug'), max_length=120, db_index=True) sort_key = models.CharField(_('sort key'), max_length=120, db_index=True) @@ -212,6 +216,7 @@ def book_upload_path(ext=None, maxlen=100): class BookMedia(models.Model): + """Represents media attached to a book.""" FileFormat = namedtuple("FileFormat", "name ext") formats = SortedDict([ ('mp3', FileFormat(name='MP3', ext='mp3')), @@ -322,6 +327,7 @@ class BookMedia(models.Model): class Book(models.Model): + """Represents a book imported from WL-XML.""" title = models.CharField(_('title'), max_length=120) sort_key = models.CharField(_('sort key'), max_length=120, db_index=True, editable=False) slug = models.SlugField(_('slug'), max_length=120, db_index=True, @@ -532,12 +538,16 @@ class Book(models.Model): # Thin wrappers for builder tasks def build_pdf(self, *args, **kwargs): + """(Re)builds PDF.""" return tasks.build_pdf.delay(self.pk, *args, **kwargs) def build_epub(self, *args, **kwargs): + """(Re)builds EPUB.""" return tasks.build_epub.delay(self.pk, *args, **kwargs) def build_mobi(self, *args, **kwargs): + """(Re)builds MOBI.""" return tasks.build_mobi.delay(self.pk, *args, **kwargs) def build_txt(self, *args, **kwargs): + """(Re)builds TXT.""" return tasks.build_txt.delay(self.pk, *args, **kwargs) @staticmethod @@ -803,7 +813,7 @@ class Book(models.Model): @classmethod def tagged_top_level(cls, tags): - """ Returns top-level books tagged with `tags'. + """ Returns top-level books tagged with `tags`. It only returns those books which don't have ancestors which are also tagged with those tags. @@ -885,7 +895,8 @@ class Book(models.Model): def _has_factory(ftype): has = lambda self: bool(getattr(self, "%s_file" % ftype)) - has.short_description = t.upper() + has.short_description = ftype.upper() + has.__doc__ = None has.boolean = True has.__name__ = "has_%s_file" % ftype return has @@ -902,6 +913,7 @@ for t in Book.formats: class Fragment(models.Model): + """Represents a themed fragment of a book.""" text = models.TextField() short_text = models.TextField(editable=False) anchor = models.CharField(max_length=120) diff --git a/apps/dictionary/models.py b/apps/dictionary/models.py index 6238ccbf2..52d687181 100644 --- a/apps/dictionary/models.py +++ b/apps/dictionary/models.py @@ -10,6 +10,7 @@ from catalogue.models import Book class Note(models.Model): + """Represents a single annotation from a book.""" book = models.ForeignKey(Book) anchor = models.CharField(max_length=64) html = models.TextField() diff --git a/doc/Makefile b/doc/Makefile index dfe1c401c..6d2a51114 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -5,84 +5,126 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = +BUILDDIR = _build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest 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 " 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 " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @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 " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: - -rm -rf _build/* + -rm -rf $(BUILDDIR)/* html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo - @echo "Build finished. The HTML pages are in _build/html." + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo - @echo "Build finished. The HTML pages are in _build/dirhtml." + @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) _build/pickle + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in _build/htmlhelp." + ".hhp project file in $(BUILDDIR)/htmlhelp." qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in _build/qthelp, like this:" - @echo "# qcollectiongenerator _build/qthelp/WolneLektury.pl.qhcp" + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/WolneLektury.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/WolneLektury.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." @echo "To view the help file:" - @echo "# assistant -collectionFile _build/qthelp/WolneLektury.pl.qhc" + @echo "# mkdir -p $$HOME/.local/share/devhelp/WolneLektury" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/WolneLektury" + @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) _build/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." + +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 LaTeX files are in _build/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo - @echo "The overview file is in _build/changes." + @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ - "or in _build/linkcheck/output.txt." + "or in $(BUILDDIR)/linkcheck/output.txt." doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ - "results in _build/doctest/output.txt." + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/architecture.rst b/doc/architecture.rst new file mode 100644 index 000000000..fd36de5a6 --- /dev/null +++ b/doc/architecture.rst @@ -0,0 +1,40 @@ +Architecture overview +===================== + +Books +----- + +Books are kept in the :py:class:`catalogue.models.Book` model. Dublin Core +metadata, read by :py:mod:`librarian.dcparser.BookInfo`, are put in the +`extra_info` JSON field. + +Authors, kinds, epochs, genres are kept in :py:class:`catalogue.models.Tag` +model with `category` field set to appriopriate value. + +:py:class:`catalogue.models.Tag` also contains :ref:`user-shelves` +and :ref:`parent-relations`. + + +User shelves +------------ + +User shelves (or tags on user's shelf) are just :py:class:`catalogue.models.Tag` +objects with ``category='set'`` and ``user`` set to the owner. Shelves' slugs +are generated automatically using :py:fun:`catalogue.utils.get_random_hash`. + + +Parent relations +---------------- + +The source of parent relations is the +:py:class:`librarian.dcparser.BookInfo.parts` metadata. + +Parent relations are kept primarily in the :py:attribute:`catalogue.models.Book.parent` +and :py:attribute:`catalogue.models.Book.parent_number` fields. + +They're also cached as :py:class:`Tag ` relations. +Each book has its tag (with :py:attribute:`slug ` +starting with ``l-``). All of book's descendants (NOT the book +itself) have its tag attached. + +Arguably, this scheme has some potential for inconsistency. diff --git a/doc/conf.py b/doc/conf.py index 60d7d55a1..edbc49f6e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # -# WolneLektury.pl documentation build configuration file, created by -# sphinx-quickstart on Tue Jun 16 18:49:15 2009. +# Wolne Lektury documentation build configuration file, created by +# sphinx-quickstart on Fri Mar 30 16:42:44 2012. # # This file is execfile()d with the current directory set to its containing dir. # @@ -12,27 +12,32 @@ # serve to show the default. import sys, os -from os.path import abspath, join, dirname - -sys.path.insert(0, abspath(join(dirname(__file__), '../wolnelektury'))) -sys.path.insert(0, abspath(join(dirname(__file__), '../apps'))) -sys.path.insert(0, abspath(join(dirname(__file__), '../lib'))) # 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.append(os.path.abspath('.')) +#sys.path.insert(0, os.path.abspath('.')) +sys.path += [ + os.path.abspath('../wolnelektury'), + os.path.abspath('../apps'), + os.path.abspath('../lib'), + os.path.abspath('../lib/librarian'), +] + +from django.core.management import setup_environ +import settings +setup_environ(settings) + + # -- 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 = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage', 'sphinx.ext.intersphinx'] - -intersphinx_mapping = { - 'http://docs.python.org/dev': None, - 'http://docs.djangoproject.com/en/dev': 'http://docs.djangoproject.com/en/dev/_objects', -} +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -41,27 +46,27 @@ templates_path = ['_templates'] source_suffix = '.rst' # The encoding of source files. -source_encoding = 'utf-8' +#source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. -project = u'WolneLektury.pl' -copyright = u'2007, Fundacja Nowoczesna Polska' +project = u'Wolne Lektury' +copyright = u'2007-2012, Fundacja Nowoczesna Polska' # 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' +version = '1.8' # The full version, including alpha/beta/rc tags. -release = '1.0' +release = '1.8' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -language = 'pl' +#language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -69,12 +74,9 @@ language = 'pl' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' -# List of documents that shouldn't be included in the build. -#unused_docs = [] - -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees = ['_build'] +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -99,8 +101,8 @@ pygments_style = 'sphinx' # -- Options for HTML output --------------------------------------------------- -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme @@ -113,7 +115,7 @@ html_theme = 'default' # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = u'%s %s - dokumentacja' % (project, version) +#html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -148,7 +150,7 @@ html_static_path = ['_static'] #html_additional_pages = {} # If false, no module index is generated. -#html_use_modindex = True +#html_domain_indices = True # If false, no index is generated. #html_use_index = True @@ -159,16 +161,22 @@ html_static_path = ['_static'] # If true, links to the reST sources are added to the pages. #html_show_sourcelink = True +# 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 = '' -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' +# 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 = 'WolneLekturypldoc' +htmlhelp_basename = 'WolneLekturydoc' # -- Options for LaTeX output -------------------------------------------------- @@ -182,8 +190,8 @@ htmlhelp_basename = 'WolneLekturypldoc' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'WolneLekturypl.tex', u'WolneLektury.pl Documentation', - u'Marek Stepniowski', 'manual'), + ('index', 'WolneLektury.tex', u'Wolne Lektury Documentation', + u'Fundacja Nowoczesna Polska', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -194,6 +202,12 @@ latex_documents = [ # 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 + # Additional stuff for the LaTeX preamble. #latex_preamble = '' @@ -201,4 +215,18 @@ latex_documents = [ #latex_appendices = [] # If false, no module index is generated. -#latex_use_modindex = True +#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', 'wolnelektury', u'Wolne Lektury Documentation', + [u'Fundacja Nowoczesna Polska'], 1) +] + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/index.rst b/doc/index.rst index f24d758b9..06314468f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,20 +1,18 @@ -.. WolneLektury.pl documentation master file, created by - sphinx-quickstart on Tue Jun 16 18:49:15 2009. +.. Wolne Lektury documentation master file, created by + sphinx-quickstart on Fri Mar 30 16:42:44 2012. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Dokumentacja serwisu WolneLektury.pl -==================================== +Welcome to Wolne Lektury's documentation! +========================================= -Spis treści ------------ .. toctree:: :maxdepth: 2 - - installation -.. autoclass:: catalogue.models.Tag - :members: + installation + publishing + architecture + reference Indices and tables ================== diff --git a/doc/installation.rst b/doc/installation.rst index 6c801c4c4..da0a9a83c 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -1,43 +1,59 @@ -========== -Instalacja -========== +===== +Setup +===== -Wymagania ---------- -Do działania serwisu wymagane są: +Requirements +------------ -* `Python 2.5 `_ -* `Django 1.0 `_ -* `lxml 2.2 `_ +* `Python 2.6+ `_ +* Everyting from the ``requirements.txt`` file +* a library for your database of choice + (see `DBs supported by Django `_) +* `puLucene `_ for search +* Librarian dependencies, see lib/librarian/README.md -Jeżeli używasz Pythona 2.4 lub chcesz użyć bazy danych innej niż SQLite, wymagana jest jeszcze: -* biblioteka do obsługi wybranej bazy danych (`biblioteki wspierane przez Django `_) +Installation +------------ +Installing database:: -Do pracy nad dokumentacją, którą teraz czytasz, potrzebne są: + cd wolnelektury + ./manage.py syncdb + ./manage.py migrate -* `Sphinx 0.6.2 `_ i zależności -Wyższe wersje wymienionych powyżej bibliotek i aplikacji powinny działać równie dobrze, aczkolwiek nie było to testowane. +Running +------- -Uruchomienie ------------- -Po instalacji wszystkich zależności należy ściągnąć kod serwisu poleceniem:: - - git clone http://jakies.repozytorium.pewnie.github +You can run the server with:: -Następnie należy zainstalować bazę danych:: - - cd wolnelektury/wolnelektury - ./manage.py syncdb - -Oraz zaimportować lektury z katalogu books:: + ./manage.py runserver - ./manage.py importbooks ../books +If you want to run lengthy tasks (like generating e-book files) in a seperate +Celery process (this is the default), you'll also need to run: -Teraz wystarczy uruchomić serwer deweloperski poleceniem:: - - ./manage.py runserver - -W wyniku powinniśmy otrzymać całkiem funkcjonalny serwer. + ./manage.py celeryd --loglevel=INFO + +If you don't want to run a separate Celery daemon, make sure you set this +option in your ``localsettings.py``:: + + CELERY_ALWAYS_EAGER = True + + +Deployment +---------- +Setup your server in fabfile.py and do:: + + fab setup + +Aside from uploading a current (git's HEAD) version of the app this will also +download all dependencies into a `virtualenv `_, +create a VHost and WSGI files for running with Apache and mod_wsgi, and +a celery config file for `supervisord `_. + +To deploy a new version into an existing setup, do: + + fab deploy +This will also check for new dependencied, migrate your app and restart the +WSGI server and Celery under supervisord. diff --git a/doc/make.bat b/doc/make.bat index e3c48caff..9b0792f0f 100644 --- a/doc/make.bat +++ b/doc/make.bat @@ -2,8 +2,11 @@ REM Command file for Sphinx documentation -set SPHINXBUILD=sphinx-build -set ALLSPHINXOPTS=-d _build/doctrees %SPHINXOPTS% . +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . if NOT "%PAPER%" == "" ( set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% ) @@ -13,99 +16,154 @@ 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. 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. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled + 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. changes to make an overview over all changed/added/deprecated items + 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 (_build\*) do rmdir /q /s %%i - del /q /s _build\* + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* goto end ) if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% _build/html + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 echo. - echo.Build finished. The HTML pages are in _build/html. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. goto end ) if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% _build/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 _build/dirhtml. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. goto end ) if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% _build/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% _build/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% _build/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 _build/htmlhelp. +.hhp project file in %BUILDDIR%/htmlhelp. goto end ) if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% _build/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 _build/qthelp, like this: - echo.^> qcollectiongenerator _build\qthelp\WolneLektury.pl.qhcp +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\WolneLektury.qhcp echo.To view the help file: - echo.^> assistant -collectionFile _build\qthelp\WolneLektury.pl.ghc + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\WolneLektury.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% _build/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" == "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 LaTeX files are in _build/latex. + echo.Build finished. The manual pages are in %BUILDDIR%/man. goto end ) if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% _build/changes + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 echo. - echo.The overview file is in _build/changes. + echo.The overview file is in %BUILDDIR%/changes. goto end ) if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% _build/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 _build/linkcheck/output.txt. +or in %BUILDDIR%/linkcheck/output.txt. goto end ) if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% _build/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 _build/doctest/output.txt. +results in %BUILDDIR%/doctest/output.txt. goto end ) diff --git a/doc/publishing.rst b/doc/publishing.rst new file mode 100644 index 000000000..57017380a --- /dev/null +++ b/doc/publishing.rst @@ -0,0 +1,9 @@ +Publishing books +================ + +You can import XML files from a directory by running:: + + ./manage.py importbooks ../books + +You can publish a single XML by using publishing form in admin, +or the publishing API. \ No newline at end of file diff --git a/doc/reference.rst b/doc/reference.rst new file mode 100644 index 000000000..cbfe8203e --- /dev/null +++ b/doc/reference.rst @@ -0,0 +1,92 @@ +Reference +========= + +.. :py:mod:catalogue + +Catalogue +--------- + +.. automodule:: catalogue + +.. automodule:: catalogue.models + +.. autoclass:: catalogue.models.Book + :members: + +.. autoclass:: catalogue.models.Fragment + :members: + +.. autoclass:: catalogue.models.Tag + :members: + +.. autoclass:: catalogue.models.Collection + :members: + + + +.. :py:mod:dictionary + +Annotation Dictionary +--------------------- + +.. automodule:: dictionary.models + :members: + + + +.. :py:mod:pdcounter + +Public Domain Counter +--------------------- + +.. automodule:: pdcounter.models + :members: + + + +.. :py:mod:picture + +Picture repository +------------------ + +.. automodule:: picture.models + :members: + + + +.. :py:mod:social + +Social +------ + +.. automodule:: social.models + :members: + + + +.. :py:mod:sponsors + +Sponsors +-------- + +.. automodule:: sponsors.models + :members: + + + +.. :py:mod:suggest + +Suggest +------- + +.. automodule:: suggest.models + :members: + + +.. :py:mod:waiter + +Celery Waiter +------------- + +.. automodule:: waiter.models + :members: diff --git a/requirements.txt b/requirements.txt index 3c85e3153..7f020942a 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,7 +4,7 @@ Django>=1.3,<1.4 South>=0.7 # migrations for django django-pagination>=1.0 -django-rosetta>=0.5.3 +#django-rosetta>=0.5.3 django-maintenancemode>=0.9 django-piston django-jsonfield