Skip to content
Newer
Older
100644 100 lines (68 sloc) 3.8 KB
1e1a31c @k0s lazy sweep through the documents
k0s authored
1 # Documentation for the Mozmill Repository
2
3 There are several entry points where it is desirable to have documentation available:
4
5 - the MDN project page(s) for mozmill: https://developer.mozilla.org/en/Mozmill
d1a27fb @whimboo Bug 776587 - Update files for move of mozautomation/mozmill repositor…
whimboo authored
6 - the mozmill github repository: http://github.com/mozilla/mozmill
196faa4 @k0s update documentation documentation
k0s authored
7 - the python package index: http://pypi.python.org/pypi/mozmill
1e1a31c @k0s lazy sweep through the documents
k0s authored
8 - in a source checkout alongside the code
6de808c @k0s another pass at the documentation documentation so i can update the d…
k0s authored
9 - using python's `help()`
1e1a31c @k0s lazy sweep through the documents
k0s authored
10 - on the AMO page: https://addons.mozilla.org/en-US/firefox/addon/9018/
11
f3fd654 @k0s update documentation on documentation
k0s authored
12 This documentation should be consistent and available at
196faa4 @k0s update documentation documentation
k0s authored
13 each of these places. We should make it easy for developers to update
14 and add documentation as well as having accurate documentation
15 versioned with the repository and aspire to the principle of DRY as
16 much as practicable. Documentation should be a maintainable
17 and high-quality resource.
1e1a31c @k0s lazy sweep through the documents
k0s authored
18
196faa4 @k0s update documentation documentation
k0s authored
19
610d38f @k0s update documentation documentation
k0s authored
20 ## Where the Documentation Lives
1e1a31c @k0s lazy sweep through the documents
k0s authored
21
d1a27fb @whimboo Bug 776587 - Update files for move of mozautomation/mozmill repositor…
whimboo authored
22 Several packages exist in the [mozmill repository](http://github.com/mozilla/mozmill):
1e1a31c @k0s lazy sweep through the documents
k0s authored
23
dd7e57c @k0s and one more pass
k0s authored
24 - [mozmill](https://developer.mozilla.org/en/Mozmill) : driver,
1e1a31c @k0s lazy sweep through the documents
k0s authored
25 event-dispatcher, and test harness
dd7e57c @k0s and one more pass
k0s authored
26 - jsbridge : python to JavaScript bridge interface
27 - mutt : test harness for mozmill and other denizens of the Mozmill
1e1a31c @k0s lazy sweep through the documents
k0s authored
28 repo
29
dd7e57c @k0s and one more pass
k0s authored
30 Each of these packages contains a `README` file as well as
6de808c @k0s another pass at the documentation documentation so i can update the d…
k0s authored
31 possibly various other documentation files in a `docs/`
1e1a31c @k0s lazy sweep through the documents
k0s authored
32 directory. These markdown files serve as the documentation canon.
33
34
610d38f @k0s update documentation documentation
k0s authored
35 ## Where the Documentation Goes
196faa4 @k0s update documentation documentation
k0s authored
36
37 By being careful in how we organize and present information, we can
610d38f @k0s update documentation documentation
k0s authored
38 use the canonical sources in the repository to give a complete and
196faa4 @k0s update documentation documentation
k0s authored
39 consistent documentation story:
40
dd7e57c @k0s and one more pass
k0s authored
41 - [github](https://github.com) will automation display `README.md`
42 files present in directories
43 - the python `setup.py` files can read the contents of the `README`
196faa4 @k0s update documentation documentation
k0s authored
44 files in their directories and they will be available when the
dd7e57c @k0s and one more pass
k0s authored
45 package is distributed to [PyPI](http://pypi.python.org/pypi/)
196faa4 @k0s update documentation documentation
k0s authored
46 - the markdown will be rendered and uploaded to
47 http://developer.mozilla.org in accordance to a manifest
48
49 As of yet, it is undecided what to do about the AMO documentation. It
50 is probably best to have a `mozmill/docs/extension.txt`, but until we
51 work out that story this will be done by hand.
52
53
610d38f @k0s update documentation documentation
k0s authored
54 ## How to Update Documentation
1e1a31c @k0s lazy sweep through the documents
k0s authored
55
56 We would love any sort of help with our documentation!
57
58 - if at all possible, make a branch with your documentation changes
d1a27fb @whimboo Bug 776587 - Update files for move of mozautomation/mozmill repositor…
whimboo authored
59 and issue a pull request to http://github.com/mozilla ; this
1e1a31c @k0s lazy sweep through the documents
k0s authored
60 is the most direct way to ensure that your documentation is included
61
196faa4 @k0s update documentation documentation
k0s authored
62 - edit the MDN documents: we will go to some effort to include edits
ca907ec @k0s update documentation documentation
k0s authored
63 in the upstream documentation. In the future, I will probably write
64 a script to help with this, but as-is, we'll just mine by hand
1e1a31c @k0s lazy sweep through the documents
k0s authored
65
66
610d38f @k0s update documentation documentation
k0s authored
67 ## How to Update Documentation on MDN
1e1a31c @k0s lazy sweep through the documents
k0s authored
68
69 The documents for the mozmill repository are enumerated in the
ca907ec @k0s update documentation documentation
k0s authored
70 `docs.manifest` file for mirroring to MDN. This `docs.manifest` file
dd7e57c @k0s and one more pass
k0s authored
71 is used by the [document-it](http://k0s.org/mozilla/hg/DocumentIt)
ca907ec @k0s update documentation documentation
k0s authored
72 program to render the contents using
73 [Markdown](http://daringfireball.net/projects/markdown/) and upload it
74 to http://developer.mozilla.org/ using the API:
75
76 http://developer.mindtouch.com/en/ref/MindTouch_API/POST%3Apages%2F%2F%7Bpageid%7D%2F%2Fcontents
77
78 After you install DocumentIt, you should be able to run:
79
80 document-it -u jhammel -p notmypassword docs.manifest
81
6de808c @k0s another pass at the documentation documentation so i can update the d…
k0s authored
82 to update the documentation on MDN.
ca907ec @k0s update documentation documentation
k0s authored
83
84 The advantage of having this as a script is that documentation is
85 updated when desired so that the active version can be respected.
86
87
610d38f @k0s update documentation documentation
k0s authored
88 ## Guiding Principles
ca907ec @k0s update documentation documentation
k0s authored
89
90 - markdown should be easy to read as text. If we want HTML documents,
91 we should use HTML documents. So ensure that the associated
92 markdown documents are easy to read as text
93
94 - the canonical absolute URLs should still point to the MDN
95 documentation
96
97 - contribute to documentation! If you see something that should be
98 documented, contribute it! Don't tell someone else to do it! We're
99 all in this together.
Something went wrong with that request. Please try again.