README.md
1SpiderMonkey in-tree documentation
2==================================
3
4This directory contains documentation for selected parts of SpiderMonkey. The
5docs are published on the [Mozilla Developer Network][mdn], but this is the
6authoritative copy; the MDN pages are updated from these files by a script. At
7the moment, we have:
8
9- `js/src/doc/Debugger`, SpiderMonkey's JavaScript debugging API, commonly
10 known as `Debugger`.
11
12- `js/src/doc/SavedFrame`, SpiderMonkey's compact representation for captured
13 call stacks.
14
15and that's it.
16
17To format the documentation, you'll need to install [Pandoc][], a
18documentation format conversion program. Pandoc can convert Markdown text,
19which is pleasant to read and write, into HTML, which is what MDN expects.
20
21[mdn]: http://developer.mozilla.org "Mozilla Developer Network"
22[Pandoc]: http://www.johnmacfarlane.net/pandoc/installing.html
23
24Management scripts
25------------------
26
27There are two scripts you may want to use while working with `js/src/doc`
28subdirectories:
29
30- `format.sh [--mdn] SOURCEDIR OUTPUTDIR` produces HTML from the document
31 sources in SOURCEDIR, placing the results in OUTPUTDIR. You can then
32 check their appearance with a web browser.
33
34 Normally, format.sh arranges the links and HTML metadata so that the
35 pages view correctly when visited at `file://` URLS pointing into
36 OUTPUTDIR. However, pages published to MDN should not have the HTML
37 metadata that stand-alone pages need, and their relative positions may be
38 different; passing the `--mdn` switch tells `format.sh` to produce output
39 for publication to MDN, not for previewing on disk.
40
41 (Why are the links affected by `--mdn`? The MDN wiki allows you to create
42 a page named `.../foo`, and then create sub-pages named `.../foo/bar`.
43 This is a nice way to arrange, say, a summary page and then sub-pages
44 providing details. But it's impossible to create the parallel structure
45 on a POSIX file system: `.../foo` can't be both a file and a directory,
46 so the links that would be correct when published on the wiki cannot be
47 correct when previewing those pages on disk. Since OUTPUTDIR's layout
48 can't match that of the wiki, we make it match that of SOURCEDIR.)
49
50- `publish.sh SOURCEDIR OUTPUTDIR KEYID SECRET` calls `format.sh`, and then
51 posts the pages to MDN, using KEYID and SECRET to establish your
52 identity. This posts only changed pages, so you can run it whenever the
53 text you have is the right stuff to publish, without creating gratuitous
54 churn in the MDN page history.
55
56 To generate KEYID and SECRET, visit the [MDN API key generation page][mdnkey].
57
58[mdnkey]: https://developer.mozilla.org/en-US/keys/ "MDN API key generation"
59
60
61Why not make the wiki the authoritative copy?
62---------------------------------------------
63
64Storing documentation in the same tree as the sources it describes has several
65advantages:
66
67- It's easy to handle documentation changes as part of the same review process
68 we use for code changes. A patch posted to Bugzilla can contain code, test,
69 and doc changes, all of which can be discussed together.
70
71- The version control system that manages the code also manages its
72 documentation. Branching the code (for Nightly, Aurora, Beta, or Release)
73 branches the docs as well, so one can always find the docs that match the
74 code in a given release stage.
75
76- Documentation for proposed changes has a natural home: in the patches
77 that implement the change (or, at least, in a patch attached to the bug
78 discussing the change). There's no need to include "(not yet
79 implemented)" markers in the published docs.
80
81
82Subdirectory layout and script interface
83----------------------------------------
84
85Alongside the documentation source files, the SOURCEDIR passed to
86`format.sh` should contain a file named `config.sh` describing the
87directory's contents, how to format them, and where they should be
88installed. This data is represented as executable shell code; `format.sh`
89and `publish.sh` run the subdirectory's `config.sh` script to learn what
90they should do.
91
92The only effect of running a `SOURCEDIR/config.sh` script should be to
93invoke the following commands:
94
95`base-url BASE`
96: Treat BASE as the common prefix for some URLs appearing as arguments to
97 subsequently executed commands (other than resource files). In
98 describing the other commands, we use the metavariable RELATIVE-URL for
99 URLs that are relative to BASE.
100
101 This command should appear before those taking RELATIVE-URL arguments.
102
103 BASE is treated as the root directory of the tree of formatted files.
104 If OUTPUTDIR is the output directory passed to `format.sh` or
105 `publish.sh`, then formatted files appear in OUTPUTDIR at the paths
106 they would appear on MDN relative to BASE.
107
108`markdown FILE RELATIVE-URL`
109: Treat FILE as Markdown source for a documentation page to be published
110 at RELATIVE-URL.
111
112`label LABEL [FRAGMENT] [TITLE]`
113: Define a label for use in Markdown reference-style links referring to
114 the file given in the preceding `markdown` command. If the second
115 argument begins with a `#` character, it is taken to be an HTML
116 fragment identifier; the link refers to that fragment in the page.
117 TITLE, if present, is the title for the link.
118
119 For example:
120
121 base-url https://devmo/Tools/
122 markdown Conventions.md Debugger-API/Conventions
123 label conventions "Debugger API: general conventions"
124 label cv #completion-values "Debugger API: completion values"
125
126 would mean that `Conventions.md` should be processed to create
127 `https://devmo/Tools/Debugger-API/Conventions`; that Markdown files can
128 refer to that page like this:
129
130 ... follows some [common conventions][conventions] which ...
131
132 and to the `#completion-values` fragment in that page like this:
133
134 ... is passed a [completion value][cv] indicating ...
135
136`absolute-label LABEL URL [TITLE]`
137: For reference-style links in this directory's Markdown files, define
138 LABEL to refer to URL, an absolute URL. TITLE is an optional link title.
139
140`resource LABEL FILE URL`
141: Treat FILE as a resource file (an image, for example) that should
142 appear at URL. Since MDN likes to place "attachments" like images under
143 different URL prefixes than the wiki pages themselves, URL is not
144 relative to the BASE passed to base-url.
145
146 LABEL can be the empty string if no Markdown documents need to refer to
147 this resource file. (For example, the Markdown might use an SVG file,
148 which in turn use the resource file.)
149
150 Unfortunately, `publish.sh` can't automatically post these resources to
151 MDN at the moment. However, it will check if the contents have changed,
152 and print a warning.
153
154
155This ought to be integrated with mach
156-------------------------------------
157
158Indeed. It should somehow be unified with 'mach doc', which seems to
159format in-tree docs of a different kind, and use a different markup
160language (ReStructuredText) and a different formatter (Sphinx).
161