Mercurial > jouvence

annotate docs/index.rst @ 31:9ae14e9615e6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: Add Sphynx documentation and code docstrings.
author Ludovic Chabant <ludovic@chabant.com>
date Sun, 15 Jan 2017 22:41:49 -0800
parents
children 7c39da93a0ce
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
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 ########
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 JOUVENCE
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
4 ########
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
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7 `Fountain`_ is a plain text markup language for screenwriting. Jouvence
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8 is a Python package for parsing and rendering Fountain documents.
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
9
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10 Jouvence supports:
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
11
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
12 * Most of the Fountain specification (see limitations below).
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13 * Rendering to HTML and terminals.
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
14
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
15 .. _fountain: http://fountain.io/
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
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
18 Installation
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
19 ============
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
20
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
21 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
22 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
23
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
24 You can install Jouvence the usual way::
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
25
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26 pip install jouvence
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
27
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
28 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
29 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
30
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
31 jouvence <path-to-fountain-file>
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
32
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33 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
34 styles.
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 .. _virtualenv: https://virtualenv.pypa.io/en/stable/
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
37
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 Usage
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 The Jouvence API goes pretty much like this::
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
43
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
44 from jouvence.parser import JouvenceParser
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
45 from jouvence.html import HtmlDocumentRenderer
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 parser = JouvenceParser()
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
48 document = parser.parse(path_to_file)
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
49 renderer = HtmlDocumentRenderer()
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
50 with open(path_to_output, 'w') as fp:
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
51 renderer.render_doc(document, fp)
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
52
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
53
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
54
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
55 Limitations
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 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
59 are not implemented:
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 * Dual dialogue
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
62 * 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
63
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
64
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
65
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
66 Documentation
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 .. toctree::
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
70 :maxdepth: 2
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 api
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
73
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 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
76
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
77 * :ref:`genindex`
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
78 * :ref:`modindex`
9ae14e9615e6 docs: Add Sphynx documentation and code docstrings.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
79 * :ref:`search`