Mercurial > jouvence

annotate docs/index.rst @ 35:6fb4d60b1e23 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added tag 0.4.0 for changeset 093bf35461ba
author Ludovic Chabant <ludovic@chabant.com>
date Tue, 17 Jan 2017 09:18:54 -0800
parents 093bf35461ba
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
31
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1
33
7c39da93a0ce docs: Add logo, do a few text changes.
Ludovic Chabant <ludovic@chabant.com>
parents: 31
diff changeset
2 .. image:: _static/jouvence.jpg
31
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3
33
7c39da93a0ce docs: Add logo, do a few text changes.
Ludovic Chabant <ludovic@chabant.com>
parents: 31
diff changeset
4 Jouvence is a Python package for parsing and rendering `Fountain`_ documents.
31
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
6 Jouvence supports:
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8 * Most of the Fountain specification (see limitations below).
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
9 * Rendering to HTML and terminals.
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10
34
093bf35461ba docs: Add links to BitBucket/GitHub.
Ludovic Chabant <ludovic@chabant.com>
parents: 33
diff changeset
11 The code is available on `BitBucket`_ and `GitHub`_.
093bf35461ba docs: Add links to BitBucket/GitHub.
Ludovic Chabant <ludovic@chabant.com>
parents: 33
diff changeset
12
31
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13 .. _fountain: http://fountain.io/
34
093bf35461ba docs: Add links to BitBucket/GitHub.
Ludovic Chabant <ludovic@chabant.com>
parents: 33
diff changeset
14 .. _bitbucket: https://bitbucket.org/ludovicchabant/jouvence
093bf35461ba docs: Add links to BitBucket/GitHub.
Ludovic Chabant <ludovic@chabant.com>
parents: 33
diff changeset
15 .. _github: https://github.com/ludovicchabant/Jouvence
31
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
16
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
17
33
7c39da93a0ce docs: Add logo, do a few text changes.
Ludovic Chabant <ludovic@chabant.com>
parents: 31
diff changeset
18 Quickstart
7c39da93a0ce docs: Add logo, do a few text changes.
Ludovic Chabant <ludovic@chabant.com>
parents: 31
diff changeset
19 ==========
7c39da93a0ce docs: Add logo, do a few text changes.
Ludovic Chabant <ludovic@chabant.com>
parents: 31
diff changeset
20
31
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
21 Installation
33
7c39da93a0ce docs: Add logo, do a few text changes.
Ludovic Chabant <ludovic@chabant.com>
parents: 31
diff changeset
22 ------------
31
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
23
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
24 As with many Python packages, it's recommended that you use `virtualenv`_,
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
25 but since Jouvence doesn't have many dependencies, you should be fine.
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
27 You can install Jouvence the usual way::
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
28
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
29 pip install jouvence
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
30
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
31 If you want to test that it works, you can feed it a Fountain screenplay and
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
32 see if it prints it nicely in your terminal::
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
34 jouvence <path-to-fountain-file>
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
35
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
36 You should then see the Fountain file rendered with colored and indented
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
37 styles.
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
38
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
39 .. _virtualenv: https://virtualenv.pypa.io/en/stable/
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
40
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
41
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
42 Usage
33
7c39da93a0ce docs: Add logo, do a few text changes.
Ludovic Chabant <ludovic@chabant.com>
parents: 31
diff changeset
43 -----
31
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
44
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
45 The Jouvence API goes pretty much like this::
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
46
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
47 from jouvence.parser import JouvenceParser
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
48 from jouvence.html import HtmlDocumentRenderer
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
49
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
50 parser = JouvenceParser()
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
51 document = parser.parse(path_to_file)
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
52 renderer = HtmlDocumentRenderer()
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
53 with open(path_to_output, 'w') as fp:
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
54 renderer.render_doc(document, fp)
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
55
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
56
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
57
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
58 Limitations
33
7c39da93a0ce docs: Add logo, do a few text changes.
Ludovic Chabant <ludovic@chabant.com>
parents: 31
diff changeset
59 -----------
31
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
60
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
61 Jouvence doesn't support the complete Fountain syntax yet. The following things
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
62 are not implemented:
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
63
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
64 * Dual dialogue
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
65 * Proper Unicode support (although Fountain's spec greatly assumes English screenplays, sadly).
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
66
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
67
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
68
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
69 Documentation
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
70 =============
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
71
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
72 .. toctree::
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
73 :maxdepth: 2
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
74
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
75 api
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
76
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
77
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
78 If you can't find what you're looking for, have a look here:
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
79
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
80 * :ref:`genindex`
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
81 * :ref:`modindex`
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
82 * :ref:`search`