Commits

Kirill Simonov  committed 3c527a0

Updated documentation to use external sphinxcontrib-{htsql,texfigure} extensions.

  • Participants
  • Parent commits 4e5da44

Comments (0)

Files changed (7)

 # 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.ifconfig', 'sphinx.ext.autodoc',
-              'sphinxcontrib.htsqldoc', 'sphinxcontrib.texdiag']
+              'sphinxcontrib.htsql', 'sphinxcontrib.texfigure']
 
 # The default URL of an HTSQL service.
-htsql_server = 'http://demo.htsql.org'
+htsql_root = 'http://demo.htsql.org'
 
 # Keep RST error messages in the output.
 keep_warnings = True

File doc/overview.rst

 HTSQL is a Web Service
 ----------------------
 
-.. vsplit::
+.. container:: vsplit
 
    .. sourcecode:: text
 
 HTSQL is a Relational Database Gateway
 --------------------------------------
 
-.. vsplit::
+.. container:: vsplit
 
    .. htsql:: /school
-      :hide:
+      :no-output:
 
    .. sourcecode:: sql
 
 HTSQL is an Advanced Query Language
 -----------------------------------
 
-.. vsplit::
+.. container:: vsplit
 
    .. htsql::
-      :hide:
+      :no-output:
 
       /school{name,
               count(program),
 HTSQL is a Communication Tool
 -----------------------------
 
-.. vsplit::
+.. container:: vsplit
 
    .. sourcecode:: html
 
         across each of its departments?
 
    .. htsql::
-      :hide:
+      :no-output:
 
       /school{name, campus,
               count(program),
 HTSQL is a Python Library
 -------------------------
 
-.. vsplit::
+.. container:: vsplit
 
    .. sourcecode:: python
 
 :doc:`tutorial`.  For the purposes of this section, we use a
 fictitious university schema.
 
-.. diagram:: dia/administrative-directory-small-schema.tex
+.. texfigure:: dia/administrative-directory-small-schema.tex
    :align: center
 
 This data model has two top-level tables, ``school`` and ``department``,
 
 .. htsql::
    :cut: 4
-   :hide:
+   :no-output:
 
     /department{name, school.campus}
 
 
 .. htsql::
    :cut: 4
-   :hide:
+   :no-output:
 
     /department{name, count(course?credits>2)}
 
 
 .. htsql::
    :cut: 4
-   :hide:
+   :no-output:
 
     /school^campus {campus, count(school.department)}
 
 
 .. htsql::
    :cut: 4
-   :hide:
+   :no-output:
 
     /department.define(
          count_courses($level) := count(course?no>=$level*100
 
 .. htsql::
    :cut: 4
-   :hide:
+   :no-output:
 
      /school?exists(program)
        {name, avg(department.count(course?credits>3))}

File doc/ref/functions.rst

 headers and footers.
 
 .. htsql:: /department{school,*}/:html
-   :plain:
-   :hide:
+   :raw:
+   :no-output:
 
 .. htsql:: /department{school,*}/:txt
-   :plain:
+   :raw:
    :cut: 12
 
 Object Output
 output structure, such as a Javascript program or XSLT stylesheet.
 
 .. htsql:: /department{school,*}.limit(3)/:json
-   :plain:
+   :raw:
 
 .. htsql:: /department{school,*}.limit(3)/:xml
-   :plain:
+   :raw:
 
 
 Tabular Output
 output data on subsequent rows.
 
 .. htsql:: /department{school,*}/:csv
-   :plain:
+   :raw:
    :cut: 3
 
 .. htsql:: /department{school,*}/:tsv
-   :plain:
+   :raw:
    :cut: 3
 
 Generic Output
 
 
 .. htsql:: /department{school,*}.limit(3)/:raw
-   :plain:
+   :raw:
 
 Query Debug
 -----------
 understanding what's going on under the hood.
 
 .. htsql:: /department{school,*}/:sql
-   :plain:
+   :raw:
 
 
 .. vim: set spell spelllang=en textwidth=72:

File doc/ref/model.rst

 a school of *Engineering* with an associated department of *Computer
 Science*, which offers a *Database Theory* course, etc.:
 
-.. diagram:: ../dia/model-and-instance.tex
+.. texfigure:: ../dia/model-and-instance.tex
    :align: center
 
 
 student enrollment database (most of the domain nodes and attribute
 arrows are omitted for clarity).
 
-.. diagram:: ../dia/sample-model.tex
+.. texfigure:: ../dia/sample-model.tex
    :align: center
 
 A *navigation* in the model graph is a path, or a sequence of arrows,
 The unit node contains a single value, which is called a *unit*
 and denoted by ``@``.
 
-.. diagram:: ../dia/sample-instance-1.tex
+.. texfigure:: ../dia/sample-instance-1.tex
    :align: center
 
 .. note::
 The following diagram visualizes the navigation
 ``school.department.name`` on a specific database instance.
 
-.. diagram:: ../dia/sample-instance-2.tex
+.. texfigure:: ../dia/sample-instance-2.tex
    :align: center
 
 
 The following diagram visualises a singular link ``program.school``
 and a plural link ``school.department``.
 
-.. diagram:: ../dia/singular-links.tex
+.. texfigure:: ../dia/singular-links.tex
    :align: center
 
 Total and Partial Arrows
 The following diagram shows a total link ``program.school`` and a
 partial attribute ``school.campus``.
 
-.. diagram:: ../dia/total-links.tex
+.. texfigure:: ../dia/total-links.tex
    :align: center
 
 Unique and Non-unique Arrows
 The following diagram shows a unique attribute ``department.name`` and a
 non-unique link ``department.school``.
 
-.. diagram:: ../dia/unique-links.tex
+.. texfigure:: ../dia/unique-links.tex
    :align: center
 
 
 ``course_dept_fk`` generate three direct and three reverse links:
 
 .. htsql:: /department.school
-   :hide:
+   :no-output:
 
 .. htsql:: /school.department
-   :hide:
+   :no-output:
 
 .. htsql:: /program.school
-   :hide:
+   :no-output:
 
 .. htsql:: /school.program
-   :hide:
+   :no-output:
 
 .. htsql:: /course.department
-   :hide:
+   :no-output:
 
 .. htsql:: /department.course
-   :hide:
+   :no-output:
 
 A foreign key ``program_part_of_fk`` induces two self-referential links
 on ``program``:
 
 .. htsql:: /program.part_of
-   :hide:
+   :no-output:
 
 .. htsql:: /program.program_via_part_of
-   :hide:
+   :no-output:
 
 
 .. vim: set spell spelllang=en textwidth=72:

File doc/ref/scopes.rst

 the prefix notation only, the query takes the form:
 
 .. htsql:: /csv(/school{name, as(count(department), '# of Depts')}?campus='north')
-   :hide:
+   :no-output:
 
 References
 ----------
 This following diagram demonstrates local scopes associated with the
 unit node and class node ``school``.
 
-.. diagram:: ../dia/local-scopes.tex
+.. texfigure:: ../dia/local-scopes.tex
    :align: center
 
 Quotient Scope
 that produced this value.  This link is called a *complement* link.
 Attributes of the quotient class are values of the kernel expression.
 
-.. diagram:: ../dia/quotient-class.tex
+.. texfigure:: ../dia/quotient-class.tex
    :align: center
 
 *Quotient scope* is a local scope associated with a quotient class.
    :cut: 3
 
 .. htsql:: /program^degree {*, count(^)}
-   :hide:
+   :no-output:
 
 .. **
 

File doc/ref/syntax.rst

 by two hexdecimal digits encoding the octet value.
 
 .. htsql:: /{'HTSQL', %27HTSQL%27, %27%48%54%53%51%4C%27}
-   :query: /%7B'HTSQL',%20%27HTSQL%27,%20%27%48%54%53%51%4C%27%7D
+   :output: /%7B'HTSQL',%20%27HTSQL%27,%20%27%48%54%53%51%4C%27%7D
 
 Percent-encoding is useful for transmitting an HTSQL query via channels
 that forbid certain characters in literal form.  The list of characters
 (``%``) character itself must always be percent-encoded.
 
 .. htsql:: /{'%25'}
-   :query: /%7B'%25'%7D
+   :output: /%7B'%25'%7D
 
 A ``NUL`` character cannot appear in an HTSQL query, neither in literal
 nor in percent-encoded form.
     `- x`
 
 .. htsql:: /{'HT'+'SQL', today()-1, -6*4/5}
-   :hide:
+   :no-output:
 
 Arithmetic operators have standard precedence and associativity.
 

File doc/tutorial.rst

 single transaction, and returns the results in a format (CSV, HTML,
 JSON, etc.) requested by the user agent:
 
-.. diagram:: dia/htsql-web-service.tex
+.. texfigure:: dia/htsql-web-service.tex
    :alt: HTSQL as a web service
    :align: center
 
 business units of the university and their relationship to the
 courses offered:
 
-.. diagram:: dia/administrative-directory-schema.tex
+.. texfigure:: dia/administrative-directory-schema.tex
    :alt: Administrative Directory schema
    :align: center
 
 To title an output column, use the ``:as`` decorator:
 
 .. htsql:: /school{name, count(department) :as '%23 of Dept.'}
-   :query: /school{name,%20count(department)%20:as%20'%23%20of%20Dept.'}
+   :output: /school{name,%20count(department)%20:as%20'%23%20of%20Dept.'}
    :cut: 3
 
 Since HTSQL is a web query language, there are two characters that have
 
 .. htsql:: /course{department{school.name, name}, title}
    :cut: 4
-   :hide:
+   :no-output:
 
 For cases where you don't wish to specify each column explicitly, use
 the wildcard ``*`` selector.  The request below returns all columns from
 results in JSON format can be requested as follows:
 
 .. htsql:: /school/:json
-   :plain:
+   :raw:
 
 Other formats include ``/:txt`` for plain-text formatting, ``/:html``
 for display in web browsers, and ``/:csv`` for data exchange. 
 doesn't affect the output. You could also use a functional form:
 
 .. htsql:: /course.filter(credits<3).select(department_code, no, title)
-   :hide:
+   :no-output:
    :cut: 3 
 
 For the following two equivalent examples, we combine 3 operators --
 Suppose you have an HTSQL query that returns the school of engineering.
 
 .. htsql:: /school.filter(code='eng')
-   :hide:
+   :no-output:
 
 Now you'd like to return departments associated with this school.  This
 could be written as:
 calculated attribute ``num_dept``.
 
 .. htsql::
-   :hide:
+   :no-output:
    :cut: 3
 
    /school.define(num_dept:=count(department))
 As syntax sugar, you could combine definition and selection.
 
 .. htsql::
-   :hide:
+   :no-output:
    :cut: 3
 
    /school{name, num_dept:=count(department)}? num_dept>3
 
 .. htsql::
    :cut: 3
-   :hide:
+   :no-output:
 
    /department.define(sophomore := course?no>=200&no<300)
               {name, count(sophomore),
 
 .. htsql::
    :cut: 3
-   :hide:
+   :no-output:
 
    /department{name,
                 {count(sophomore),
 concisely defining a calculation with a parameter.
 
 .. htsql::
-   :hide:
+   :no-output:
    :cut: 3
 
    /department.define(freshman := course?no>=100&no<200,
 section as:
 
 .. htsql::
-   :hide:
+   :no-output:
    :cut: 3
 
    /department.define(
 This same request can be written using ``where``.
 
 .. htsql::
-   :hide:
+   :no-output:
    :cut: 3
 
    /course?credits>$avg_credits
 
 .. htsql:: /department?name!~'science'
    :cut: 4
-   :hide:
+   :no-output:
 
 To exclude a specific department, use the *not-equals* operator:
 
 .. htsql:: /department?name!='Management & Marketing'
    :cut: 4
-   :hide:
+   :no-output:
 
 The *equality* (``=``) and *inequality* (``!=``) operators are
 straightforward when used with numbers:
 
 .. htsql:: /department?school_code!={'eng','ns'}
    :cut: 4
-   :hide:
+   :no-output:
 
 Use the *greater-than* (``>``) operator to request departments with
 more than 20 offered courses:
 
 .. htsql:: /department?count(course)>=20
    :cut: 4
-   :hide:
+   :no-output:
 
 Using comparison operators with strings tells HTSQL to compare them
 alphabetically (once again, dependent upon database's collation).  For
 
 .. htsql:: /course?description
    :cut: 4
-   :hide:
+   :no-output:
 
 The predicate ``?description`` is treated as a short-hand for
 ``?(!is_null(description)&description!='')``.  The negated variant of