There are a lot of things that are not documented on mdn which we should identify and document as we come across them. Here are some things I came up with off the top of my head: http://etherpad.mozilla.com:9000/AAIr5Z19WQ Obviously this is not a comprehensive list. Please feel free to add anything you think should have some documentation (doesn't necessarily have to be a method in the API missing, could be a tutorial or general information page) and strike it out if it does get documented. While adding missing documentation we should also try to identify out of date information and update that as well. I sincerely believe that if we ever want Mozmill to be used by people other than the QA Automation team and the Thunderbird automation team, making the docs better is the most important thing we have to do (The Thunderbird team has even made a whole bunch of hacks that are preventing them from upgrading past 1.4.2b1 largely in part to poor documentation).

We have a query for non-documented code: https://bugzilla.mozilla.org/buglist.cgi?status_whiteboard_type=allwordssubstr&query_format=advanced&status_whiteboard=[mozmill-doc-needed]&component=Mozmill&component=Mozmill%20Utilities

Similarly, since mozmill 2.0 is going to be a big change. I have a WIP on these, but its not quite postable yet

Proposal: * JS Doc the public/private APIs * MDN for tutorials/behavioral docs * Forums for Mozmill ** Mozmill-dev ** Tools newsgroup/dev.platform/dev.qa for larger announcements ** Blogging more ** about: newsletter mention Tracking Documentation * Whiteboard flag is kinda useless * Let's track in separate bugs for behavioral bugs

So in some offline and newsgroup discussion we've decided on a basic strategy for MDN. See https://github.com/k0s/mozmill/blob/documentation/documentation.txt Please feel free to contribute to the documentation effort via pull requests or just sending me ready documentation for inclusion. My documentation branch is here for those following along https://github.com/k0s/mozmill/blob/documentation

Also of note, the documentation on wiki.m.o should be updated as well. E.g. https://wiki.mozilla.org/Auto-tools/Projects/Mozmill/RepoSetup is all kinds of wrong

So there is quite a bit of progress here. To summarize: - I wrote a program, document-it (http://brasstacks.mozilla.com/toolbox/document-it), that will take a manifest of local documentation and e.g. upload to MDN - manifests are, currently, simple mappings of local (markdown) files to page names. The manifest for the mozmill repo currently looks like mozinfo/README.md en/Mozinfo mozprocess/README.md en/Mozprocess mozprofile/README.md en/Mozprofile mozrunner/README.md en/Mozrunner jsbridge/README.md en/Mozmill/jsbridge mozmill/README.md en/Mozmill mozmill/docs/event_handlers.txt en/Mozmill/EventHandlers mozmill/docs/architecture.txt en/Mozmill/Architecture mozmill/docs/INSTALL.txt en/Mozmill/Installation documentation.txt en/Mozmill/Documentation - The above contains the pages central to mozmill and other pieces of the repository. They are not finished yet, but you can see them on the volatile staging server: https://developer-stage9.mozilla.org/en/Mozmill - The following pages won't be updated as part of this bug, as they are about downstream consumption: * https://wiki.mozilla.org/QA/Mozmill_Test_Automation * https://developer.mozilla.org/en/Mozmill_Tests * https://developer.mozilla.org/en/Mozmill/Release_Testing * https://developer.mozilla.org/en/Thunderbird/Thunderbird_MozMill_Testing * https://developer.mozilla.org/en/Mozmill/First_Steps/Tutorial%3a_Introduction_to_Mozmill - the JS API documentation *should* be updated; however, we should port it to JS doc first. http://en.wikipedia.org/wiki/JSDoc . I would recommend a separate bug for this. Even if we take this with this bug, I would recommend taking a separate patch for these. The two sets of documentation have no overlap and the patch that I'm currently working on is already huge and bitrotten

(In reply to Jeff Hammel [:jhammel] from comment #6) > - the JS API documentation *should* be updated; however, we should port it > to JS doc first. http://en.wikipedia.org/wiki/JSDoc . I would recommend a > separate bug for this. Even if we take this with this bug, I would You should better have a look at JSDoc Toolkit (code.google.com/p/jsdoc-toolkit/). That's what we are using to create the documentation in our API refactoring project. If you have questions, Geo did the investigation for it a couple of months ago and should be able to help you.

Not as part of this bug, but we should also come up with a documentation strategy for MozBase: https://wiki.mozilla.org/Auto-tools/Projects/MozBase Since so much of Mozmill and MozBase overlap, this should be carefully considered. Additionally, we'll probably want to figure out what makes sense to live on wiki.m.o, and MDN. (again, not part of this bug, just noting for posterity)

documentation patch, details to be described in subsequent comment

so wrt comment 9, I have IMHO pretty good and maintainable basic documentation. While the patch does contain (documentation-related) code changes and should be reviewed, the documentation itself is probably much more favorably reviewed from https://developer-stage9.mozilla.org/en/Mozmill and related pages. The markdown is also viewable on my documentation branch: https://github.com/k0s/mozmill/tree/documentation A few things: - the documentation strategy is detailed, in suitable form, at https://github.com/k0s/mozmill/blob/documentation/documentation.txt - pushing to MDN is a separate issue; we can do this whenever (presumedly when Mozmill 2.0 == what QA is using) and its probably not bug worthy - the URLs will all need to be fixed following pushing to MDN. Right now they are site-relative URLs so the links on stage9 work (except the absolute URLs, used when possible), but in order to be meaningful from other resources they should link to the absolute MDN URLs when applicable - stage9 is slow. It was generous that I was allowed to use it at all, so no complaining

Comment on attachment 552197 [details] [diff] [review] document all the things Review of attachment 552197 [details] [diff] [review]: ----------------------------------------------------------------- Looks great! Your zeal for documentation is definitely inspirational. All comments are minor nits. If you find your .md -> MDN doc scripts work well, I may use them for TPS. ::: README.md @@ +16,5 @@ > +from the [Github repo](http://github.com/mozautomation/mozmill): > + > + virtualenv mozmill > + cd mozmill > + . bin/activate On Windows this line is annoyingly slightly different ('source Scripts/activate'), but it's probably not worth calling out; anyone who's used to using virtualenv on Windows would know what to do. @@ +42,5 @@ > + > +- mozinfo : gathers system information > +- mozprocess : generic cross-platform process management > +- mozprofile : creates and manages user profiles for Mozilla apps > +- mozrunner : handles start/stop automation of Mozilla applications: there's an extra colon at the end @@ +55,5 @@ > +for installation. It is highly recommended that you use > +[virtualenv](http://www.virtualenv.org/) to keep your python > +environment separate from your system packages. In this way, you can > +keep multiple versions of packages around without worrying about > +cross-contamination and versioning woes needs trailing period @@ +64,5 @@ > +In addition to the python packages, several files exist at the top > +level of the repository to help keep repository management sane: > + > +- README.md : documents what the [Mozmill repository](http://github.com/mozautomation/mozmill) > + is all about; the content you're reading now All of these bullets probably need trailing periods. ::: documentation.txt @@ +56,5 @@ > + > + > +## How to Update Documentation > + > +We would love any sort of help with our documentation! bullets below probably need trailing periods @@ +89,5 @@ > +updated when desired so that the active version can be respected. > + > + > +## Guiding Principles > + bullets probably need trailing periods ::: jsbridge/README.md @@ +5,5 @@ > +jsbridge works as an > +[extension](https://github.com/mozautomation/mozmill/tree/master/jsbridge/jsbridge/extension) > +loaded into Firefox or Thunderbird > +(etc.) that opens a socket, by default on port 24242, that > +is used to mirror data structures between python-land and JavaScript-land need trailing period @@ +10,5 @@ > +The python component opens the same port and communication takes place. > + > +[JSObject](https://github.com/mozautomation/mozmill/blob/master/jsbridge/jsbridge/jsobjects.py)s > +(`jsbridge.jsbobject:JSObject`) may be used to mirror > +objects across the between python and JavaScript. missing word between "the" and "between"? ::: mozmill/README.md @@ +49,5 @@ > + > +## Running the command line client > + > +After [installing](./Installation) > +the Python package you can run Mozmill with the `mozmill` command. probably shouldn't capitalize Python here, since it isn't capitalized elsewhere on this page @@ +115,5 @@ > +- [mozinfo](/en/Mozinfo) : unified Mozilla interface to system information > +- [manifestparser](http://hg.mozilla.org/automation/ManifestDestiny) : parses test and addon manifests > + > +See [Architecture](./Architecture) for additional information on > +program design. Links like this (and (./EventHandlers), etc) don't work when this page is viewed on github; I guess they're designed to work with MDN? @@ +130,5 @@ > +It is desirable to transfer data to and from the JavaScript tests. There > +are a few mechanisms to do so: > + > +- [event handlers](./EventHandlers) send data from the JavaScript > + application layer to the python harness needs trailing period to be consistent with other bullets @@ +179,5 @@ > +browser. There are two types of shutdown/restart events: > + > +- user shutdown : the test indicates a shutdown or restart. This does > + not stop the browser but indicates that a further action will cause > + a restart or shutdown (such as triggering `Ctrl+Q`) needs trailing period ::: mozmill/docs/INSTALL.txt @@ +31,5 @@ > +Python environments. If you have `pip` or `easy_install` on your > +system, you can run `pip install virtualenv` or `easy_install > +virtualenv` to install it, or download and install from the source on > +[pypi](http://pypi.python.org/pypi/virtualenv) or the > +[github repository](https://github.com/pypa/virtualenv). As noted earlier, these instructions won't work as-is on Windows, and even worse, the method to use will vary depending on whether you're using cygwin/msys or not. Is it worth including a Windows-specific section? I don't know. Probably most potential contributors will be using linux or mac. ::: mozmill/docs/architecture.txt @@ +41,5 @@ > +object appropriate to the application under test (e.g. `FirefoxRunner`). > +Additionally, `mozrunner.CLI` consumes and exposes the arguments from > +[MozProfileCLI](https://github.com/mozautomation/mozmill/blob/master/mozprofile/mozprofile/cli.py) . > +This architecture allows mozrunner and mozprofile to exist as > +independent command line programs while making the breadth of options should this read "while making *their* breadth of options"? ::: mozmill/docs/event_handlers.txt @@ +16,5 @@ > + > +Several event listeners are added in the > +[Mozmill constructor](https://github.com/mozautomation/mozmill/blob/master/mozmill/mozmill/__init__.py) > +vital for test harness functionality. In addition, handlers may be > +passed to the constructor from which event listeners may be added. This sentence was hard for me to parse. Do you mean, "In addition, event listeners may be added by passing their handlers to the constructor"? @@ +47,5 @@ > + > +You can also add free-standing python modules as pluggable event > +listeners from the command line using the switch > +`--handler=PATH:CLASS`, where `PATH` is the path to the python file > +and `CLASS` is the name of the event handler class in the file need trailing period @@ +103,5 @@ > +return a dict of names of events to listen for mapped to the methods > +that listen to these events. > + > +Ccurrently the event type is a string by convention only. There > +have no catalog of events to be listened for. A list of applicable s/have/is/ ::: mozprocess/README.md @@ +1,5 @@ > +[mozprocess](https://github.com/mozautomation/mozmill/tree/master/mozprocess) > +provides python process management via an operating system > +and platform transparent interface to Mozilla platforms of interest. > +Mozprocess aims to ensure the ability to robustly terminate a process > +on Windows, OS X, and Linux. Mozprocess utilizes and extends I'd extend this sentence a bit, maybe something like: Mozprocess aims to provide the ability to robustly terminate a process (by timeout or otherwise), along with any child processes, on Windows, OS X, and Linux. @@ +2,5 @@ > +provides python process management via an operating system > +and platform transparent interface to Mozilla platforms of interest. > +Mozprocess aims to ensure the ability to robustly terminate a process > +on Windows, OS X, and Linux. Mozprocess utilizes and extends > +`subprocess.Popen` to these ends needs trailing period @@ +25,5 @@ > + > +`ProcessHandler` may be subclassed to handle process timeouts (by overriding > +the `onTimeout()` method), process completion (by overriding > +`onFinish()`), and to process the command output (by overriding > +`processOutputLine`). /s/processOutputLine/processOutputLine()/, for consistency ::: mozprofile/README.md @@ +1,2 @@ > +[Mozprofile](https://github.com/mozautomation/mozmill/tree/master/mozprofile) > +is python tool for creating and managing profiles for Mozilla's s/is python/is a python/

pushed to master: https://github.com/mozautomation/mozmill/commit/c02925bc32a289db771d8e05dd25a27ca2379912

Also updated: https://developer-stage9.mozilla.org/en/Mozmill

(In reply to Jonathan Griffin (:jgriffin) from comment #11) > Comment on attachment 552197 [details] [diff] [review] > document all the things > > Review of attachment 552197 [details] [diff] [review]: > ----------------------------------------------------------------- > > Looks great! Your zeal for documentation is definitely inspirational. All > comments are minor nits. > > If you find your .md -> MDN doc scripts work well, I may use them for TPS. > > ::: README.md > @@ +16,5 @@ > > +from the [Github repo](http://github.com/mozautomation/mozmill): > > + > > + virtualenv mozmill > > + cd mozmill > > + . bin/activate > > On Windows this line is annoyingly slightly different ('source > Scripts/activate'), but it's probably not worth calling out; anyone who's > used to using virtualenv on Windows would know what to do. Indeed. I intentionally avoided putting very specialized instructions for the various cases about virtualenv, since they really have nothing to do with mozmill. We should probably have a virtualenv page but first to make it a bit more widely adopted. (Also, source Scripts/activate only will work in the build environment; in msys its Scripts/activate.bat , no source since it is run in-shell and windows doesn't natively have source). > @@ +42,5 @@ > > + > > +- mozinfo : gathers system information > > +- mozprocess : generic cross-platform process management > > +- mozprofile : creates and manages user profiles for Mozilla apps > > +- mozrunner : handles start/stop automation of Mozilla applications: > > there's an extra colon at the end Fixed. > @@ +55,5 @@ > > +for installation. It is highly recommended that you use > > +[virtualenv](http://www.virtualenv.org/) to keep your python > > +environment separate from your system packages. In this way, you can > > +keep multiple versions of packages around without worrying about > > +cross-contamination and versioning woes > > needs trailing period Fixed. > @@ +64,5 @@ > > +In addition to the python packages, several files exist at the top > > +level of the repository to help keep repository management sane: > > + > > +- README.md : documents what the [Mozmill repository](http://github.com/mozautomation/mozmill) > > + is all about; the content you're reading now > > All of these bullets probably need trailing periods. So I didn't fix any of the bullet points and trailing periods. Most of them are sentence fragments and....you don't put periods after sentence fragments (except when before a new full sentence). > ::: jsbridge/README.md > @@ +5,5 @@ > > +jsbridge works as an > > +[extension](https://github.com/mozautomation/mozmill/tree/master/jsbridge/jsbridge/extension) > > +loaded into Firefox or Thunderbird > > +(etc.) that opens a socket, by default on port 24242, that > > +is used to mirror data structures between python-land and JavaScript-land > > need trailing period Fixed. > @@ +10,5 @@ > > +The python component opens the same port and communication takes place. > > + > > +[JSObject](https://github.com/mozautomation/mozmill/blob/master/jsbridge/jsbridge/jsobjects.py)s > > +(`jsbridge.jsbobject:JSObject`) may be used to mirror > > +objects across the between python and JavaScript. > > missing word between "the" and "between"? Nope. Extra word, 'the'; good catch! > ::: mozmill/README.md > @@ +49,5 @@ > > + > > +## Running the command line client > > + > > +After [installing](./Installation) > > +the Python package you can run Mozmill with the `mozmill` command. > > probably shouldn't capitalize Python here, since it isn't capitalized > elsewhere on this page Fixed. > @@ +115,5 @@ > > +- [mozinfo](/en/Mozinfo) : unified Mozilla interface to system information > > +- [manifestparser](http://hg.mozilla.org/automation/ManifestDestiny) : parses test and addon manifests > > + > > +See [Architecture](./Architecture) for additional information on > > +program design. > > Links like this (and (./EventHandlers), etc) don't work when this page is > viewed on github; I guess they're designed to work with MDN? Indeed. All of the links should be made absolute, but only after they're pushed to MDN. They're the way they are for staging now (and to clue us in as to what they should be), but they should all be absolute links to MDN. > ::: mozmill/docs/INSTALL.txt > @@ +31,5 @@ > > +Python environments. If you have `pip` or `easy_install` on your > > +system, you can run `pip install virtualenv` or `easy_install > > +virtualenv` to install it, or download and install from the source on > > +[pypi](http://pypi.python.org/pypi/virtualenv) or the > > +[github repository](https://github.com/pypa/virtualenv). > > As noted earlier, these instructions won't work as-is on Windows, and even > worse, the method to use will vary depending on whether you're using > cygwin/msys or not. Is it worth including a Windows-specific section? I > don't know. Probably most potential contributors will be using linux or mac. Again, I'd rather take that as a separate issue. There's much that needs to be cleaned up as part of the installation story, and probably using virtualenv needs its own documentation rather than living in each page where we recommend it (I also don't tell how to use mercurial or git, for instance, or what a computer is, or Mozilla, etc). I've linked to several resources that give that information and we can provide more documentation as it becomes a sticking point. > ::: mozmill/docs/architecture.txt > @@ +41,5 @@ > > +object appropriate to the application under test (e.g. `FirefoxRunner`). > > +Additionally, `mozrunner.CLI` consumes and exposes the arguments from > > +[MozProfileCLI](https://github.com/mozautomation/mozmill/blob/master/mozprofile/mozprofile/cli.py) . > > +This architecture allows mozrunner and mozprofile to exist as > > +independent command line programs while making the breadth of options > > should this read "while making *their* breadth of options"? Indeed it should; thanks! > ::: mozmill/docs/event_handlers.txt > @@ +16,5 @@ > > + > > +Several event listeners are added in the > > +[Mozmill constructor](https://github.com/mozautomation/mozmill/blob/master/mozmill/mozmill/__init__.py) > > +vital for test harness functionality. In addition, handlers may be > > +passed to the constructor from which event listeners may be added. > > This sentence was hard for me to parse. Do you mean, "In addition, event > listeners may be added by passing their handlers to the constructor"? Hmmm....no. I guess I didn't make this very clear. So handlers are classes that may add arbitrary listeners. I'll try to make this clearer going forward, but probably not until after 2.0 is out the door. > @@ +47,5 @@ > > + > > +You can also add free-standing python modules as pluggable event > > +listeners from the command line using the switch > > +`--handler=PATH:CLASS`, where `PATH` is the path to the python file > > +and `CLASS` is the name of the event handler class in the file > > need trailing period Fixed. > @@ +103,5 @@ > > +return a dict of names of events to listen for mapped to the methods > > +that listen to these events. > > + > > +Ccurrently the event type is a string by convention only. There > > +have no catalog of events to be listened for. A list of applicable > > s/have/is/ Thanks. Fixed. > ::: mozprocess/README.md > @@ +1,5 @@ > > +[mozprocess](https://github.com/mozautomation/mozmill/tree/master/mozprocess) > > +provides python process management via an operating system > > +and platform transparent interface to Mozilla platforms of interest. > > +Mozprocess aims to ensure the ability to robustly terminate a process > > +on Windows, OS X, and Linux. Mozprocess utilizes and extends > > I'd extend this sentence a bit, maybe something like: Mozprocess aims to > provide the ability to robustly terminate a process (by timeout or > otherwise), along with any child processes, on Windows, OS X, and Linux. Thanks, done. > @@ +2,5 @@ > > +provides python process management via an operating system > > +and platform transparent interface to Mozilla platforms of interest. > > +Mozprocess aims to ensure the ability to robustly terminate a process > > +on Windows, OS X, and Linux. Mozprocess utilizes and extends > > +`subprocess.Popen` to these ends > > needs trailing period Fixed. > @@ +25,5 @@ > > + > > +`ProcessHandler` may be subclassed to handle process timeouts (by overriding > > +the `onTimeout()` method), process completion (by overriding > > +`onFinish()`), and to process the command output (by overriding > > +`processOutputLine`). > > /s/processOutputLine/processOutputLine()/, for consistency Fixed. > ::: mozprofile/README.md > @@ +1,2 @@ > > +[Mozprofile](https://github.com/mozautomation/mozmill/tree/master/mozprofile) > > +is python tool for creating and managing profiles for Mozilla's > > s/is python/is a python/ Awww! I kinda like "is python tool". Fine fine....I'll abandon my caveman dialog and fix it.

We still need to push to MDN, but that can be done whenever.