jenkins-bot has submitted this change and it was merged.
Change subject: Add first pass of guides
......................................................................
Add first pass of guides
This is a first pass, so there could maybe be more details, and there could
almost certainly be more useful or structured information. But it explains
the gist of what we want, and that's a good start.
Change-Id: If1680b23ed3ffad56d889232a26a5faad05072d3
---
A js/doc.guides.json
A js/guides/apiuse/README.md
A js/guides/devsetup/README.md
A js/guides/setup/README.md
M js/jsduck-conf.json
5 files changed, 307 insertions(+), 0 deletions(-)
Approvals:
Cscott: Looks good to me, approved
jenkins-bot: Verified
diff --git a/js/doc.guides.json b/js/doc.guides.json
new file mode 100644
index 0000000..135b148
--- /dev/null
+++ b/js/doc.guides.json
@@ -0,0 +1,25 @@
+[
+ {
+ "title": "Parsoid guides",
+ "items": [
+ {
+ "name": "setup",
+ "url": "guides/setup",
+ "title": "Setting up Parsoid",
+ "description": "Get Parsoid set up on your
machine and start using it."
+ },
+ {
+ "name": "devsetup",
+ "url": "guides/devsetup",
+ "title": "Setting up Parsoid for development",
+ "description": "Get Parsoid set up and start
developing for it."
+ },
+ {
+ "name": "apiuse",
+ "url": "guides/apiuse",
+ "title": "Using Parsoid's API",
+ "description": "How to use Parsoid's HTTP API
to parse and roundtrip wikitext."
+ }
+ ]
+ }
+]
diff --git a/js/guides/apiuse/README.md b/js/guides/apiuse/README.md
new file mode 100644
index 0000000..1c5a6d6
--- /dev/null
+++ b/js/guides/apiuse/README.md
@@ -0,0 +1,53 @@
+# Using Parsoid's API
+
+If you're a developer looking to deal with MediaWiki's wikitext output, but
+you would much prefer it to be an HTML DOM, then Parsoid can best help you
+through its HTTP API that serves HTML (or JSON) responses.
+
+## /{wiki prefix}/{article name}
+
+### GET
+
+If you make a GET request to the API, to a URI that represents a valid
+interwiki prefix and an article name, you will get back an HTML document with
+a bunch of extra information used for round-tripping. You can use this to do
+basic parsing of existing wiki pages.
+
+#### Responses
+
+Assuming all goes well, you will receive a 200 OK response with the text of
+the HTML document. But what if things go wrong?
+
+##### 401 Unauthorized
+
+This means that the wiki you were trying to access doesn't allow read access
+to anonymous users. Parsoid will never work for this wiki, and you should
+report this as a bug in the server's configuration.
+
+##### 404 Not Found
+
+This means what you would expect - the page was not there on the wiki. It
+might also indicate that this is a redirect to a different wiki - those do
+exist - and that you should use the URL in the text of the response instead.
+
+##### 500 Internal Server Error
+
+The least helpful of error codes. We do try to include more information in the
+body of the response, but it may not always be as helpful as we intend.
+
+### POST
+
+If you POST to the API with the same URI scheme, in a form-encoded format
+with a data member named "content", the API will round-trip the HTML in the
+content member to wikitext, and return that. You can use this to do basic
+round-tripping of existing, potentially modified versions of existing
+wiki pages.
+
+## /_bugs/
+
+### POST
+
+If you POST to the /_bugs/ URI, you'll be able to report a bug to the system
+administrators running the instance of Parsoid that you're accessing. You
+might use this to allow users to submit Parsoid bug reports, or even to report
+bugs you expose through your use of the Parsoid service automatically.
diff --git a/js/guides/devsetup/README.md b/js/guides/devsetup/README.md
new file mode 100644
index 0000000..69b6b4e
--- /dev/null
+++ b/js/guides/devsetup/README.md
@@ -0,0 +1,144 @@
+# Setting up Parsoid for development
+
+Hopefully by now you've read the [setup guide](#!/guide/setup), which explains
+how to get the Parsoid code, how to run our basic tools, and points here for
+those who want to do more. The setup described therein is required for this
+document also.
+
+## Setup
+
+Setup for developing Parsoid is, thankfully, brief.
+
+### Getting test suite
+
+We use MediaWiki's core parser test suite rather than writing our own. This
+sets a very high bar for our success, but it also means that we can ensure
+totally correct behavior if the tests are passing.
+
+To fetch the test suite, go to the `js/tests/` directory and run this:
+
+```
+$ node fetch-parserTests.txt.js
+```
+
+This should pull the current parser tests to the tests directory. You may want
+to run this command from time to time to make sure the tests are up to date.
+
+### Getting a Gerrit account and setting it up in Parsoid's repository
+
+If you want to submit patches to our project - and we highly suggest that you
+do - you should definitely
+[sign up for an account on
Gerrit](https://wikitech.wikimedia.org/w/index.php?title=Special:UserLogin&returnto=Help%3AGetting+Started&type=signup)
+and set it up on your local git repository.
+
+Once you have an account, setting up a gerrit remote is pretty simple:
+
+```
+$ git remote add gerrit
ssh://<YOUR-USERNAME>@gerrit.wikimedia.org:29418/mediawiki/extensions/Parsoid.git
+```
+
+Be sure to replace the `<YOUR-USERNAME>` bit with your username on Gerrit -
+you can use your
+[user settings page](https://gerrit.wikimedia.org/r/#/settings/)
+to figure out exactly what that is.
+
+After that, you should also install the git-review tool, which makes it very
+simple to submit code for review.
+[The MediaWiki documentation
wiki](http://www.mediawiki.org/wiki/Gerrit/Tutorial#Installing_git-review)
+has a whole section on the subject.
+
+## Making changes
+
+In making changes to Parsoid, you should use [our documentation](#!/api) to
+help guide you through the code. Where you aren't sure how to proceed, and if
+you think you're lost, you can try joining our IRC channel,
+`#mediawiki-parsoid` on `irc.freenode.net`, and asking for help there.
+
+## Testing your changes
+
+There are four major things you should test before you submit a change:
+
+* tests/parserTests.js
+* tests/parse.js
+* tests/roundtrip-test.js
+* api/server.js
+
+### parserTests.js
+
+To run the parser tests, go to the `js/tests/` directory, and run:
+
+```
+$ ./runtests.sh
+```
+
+This script is there to help remember the test modes and options we use, and
+to assist in telling what tests change after a commit. If you want to know
+about test changes in your commit, you should also run
+
+```
+$ ./runtests.sh -c
+```
+
+in this directory before you start working - it will commit the changes to a
+git repository in `js/tests/results/` that will then be used to diff the test
+results from the next test run.
+
+If you prefer to run the parser tests on your own, something like
+
+```
+$ node parserTests --help
+```
+
+should tell you all you need to choose the right options.
+
+### parse.js
+
+This tool is described briefly in the [setup instructions](#!/guide/setup) as
+a useful tool for testing functionality, or parsing bits of wikitext. We also
+need to make sure it runs properly after your changes. Run something like
+
+```
+$ echo "''Non'''-trivial'' wikitext''' [[with links]] {{echo|and templates}} |
node parse --wt2wt
+```
+
+from the `js/tests/` directory. That command should test a sufficient number
+of the parser's - and serializer's - features that we can be confident in a
+positive result.
+
+### roundtrip-test.js
+
+This script is something we use to test against actual wiki articles. You can
+specify which wiki you want to use with the --wiki option, but it defaults to
+English Wikipedia which should be sufficient. Running
+
+```
+$ node roundtrip-test.js "Barack Obama"
+```
+
+is a simple and stereotypical test case. If the script runs without issue,
+then it should be fine.
+
+### server.js
+
+This is a more complicated one to test. You'll need to actually run the API
+server - see the [setup instructions](#!/guide/setup) for how to do so - and
+load a page in your browser to make sure the API still responds accurately to
+responses. Loading
+[French Wikipedia's page on Obama](http://localhost:8000/_rt/fr/Barack_Obama)
+is a pretty good test, so if that page loads completely, and there are no
+errors in the server's output, then you can probably call this test passed.
+
+## Submitting changes
+
+If you've followed the above instructions, you have git-review installed,
+you've configured a gerrit remote, and your patch passed all of the tests,
+then you can submit your change with
+
+```
+$ git add <files> # any files you changed
+$ git commit # enter a commit summary
+$ git review # send it for review
+```
+
+After you submit the patch, the Parsoid team will likely get around to
+reviewing it within a day or two, depending on their schedules.
diff --git a/js/guides/setup/README.md b/js/guides/setup/README.md
new file mode 100644
index 0000000..1e75f69
--- /dev/null
+++ b/js/guides/setup/README.md
@@ -0,0 +1,84 @@
+# Setting up Parsoid
+
+Welcome to Parsoid! Parsoid is meant to be a simple, featureful parser for
+wikitext that produces HTML DOMs which can then be turned back into wikitext,
+even after modifications.
+
+If you just want to turn wikitext into HTML, and don't need to round-trip back
+into wikitext, you may be better off with another project, but Parsoid will
+probably do what you want.
+
+## Prerequisites
+
+You'll need:
+
+* [git](http://git-scm.com)
+* [node.js](http://nodejs.org)
+* [npm](http://npmjs.org) (Node.js Package Manager)
+
+### A note about node.js
+
+In a lot of places, you will see this document refer to a `node` executable.
+On newer Debian systems, and maybe in other places, however, node.js is run by
+a command `nodejs`. You should experiment with both and be conscious of which
+one you need to use as you read this guide.
+
+## Getting the code
+
+To get the code, you'll need to clone our git repository. Run this command:
+
+```
+$ git checkout
https://gerrit.wikimedia.org/r/p/mediawiki/extensions/Parsoid.git
+```
+
+## Installing node.js dependencies
+
+Now that you have the code, you can run npm to get all of the necessary
dependencies. Get into the `js/` directory of the Parsoid repository - if you
ran the above command verbatim you can just run `cd Parsoid/js` - and run:
+
+```
+$ npm install
+```
+
+## Running the API
+
+The API is the main reason you might want to run Parsoid, because VisualEditor
+uses it to do a lot of backend work. To run the API in a terminal, go to the
+`js/api/` directory in the Parsoid repository and run the following:
+
+```
+$ node server
+```
+
+There is also, in the `js/api/` directory, a nice runserver.sh script that will
+perhaps be useful to someone running the API as a more permanent service. The
+script was originally written for Wikimedia's internal purposes, but it could
+be useful anywhere if it was tweaked a little bit.
+
+Note that if you want to enable any options, or change any settings, you will
+need to copy the example `localsettings.js` file from the `js/api/` directory
+and use it to define any of your desired options.
+
+## Running the basic parse tool
+
+If you aren't looking to run an API service, or VisualEditor, or if you just
+want to test Parsoid's capabilities, you can use our simple parse.js script.
+This time, go to the `js/tests/` directory in the Parsoid repository and do
+something like:
+
+```
+$ echo "some harmless [[wikitext]]" | node parse
+```
+
+This will run the echoed text through the wikitext parser and show you the
+resulting HTML. You can also specify different options for different output -
+`--wt2wt` will convert wikitext to HTML and then back to wikitext, `--html2wt`
+will convert HTML to wikitext, and `--html2html` will convert HTML to wikitext
+and then back to HTML. You can test the parser this way - please use this tool
+when trying to report bugs.
+
+## More setup and usage examples
+
+If you want more, you might want to try our
+[developer setup guide](#!/guide/devsetup) if you want to see how you can run
+Parsoid's test suites, use the debug and trace flags, and perform round-trip
+testing on real wiki articles.
diff --git a/js/jsduck-conf.json b/js/jsduck-conf.json
index 1a1f32a..ab9a7c4 100644
--- a/js/jsduck-conf.json
+++ b/js/jsduck-conf.json
@@ -4,6 +4,7 @@
"--ignore-global": true,
"--builtin-classes": true,
"--output": "doc/",
+ "--guides": "./doc.guides.json",
"--": [
"./doc.basicTypes.js",
"./lib/core-upgrade.js",
--
To view, visit https://gerrit.wikimedia.org/r/55013
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: If1680b23ed3ffad56d889232a26a5faad05072d3
Gerrit-PatchSet: 3
Gerrit-Project: mediawiki/extensions/Parsoid
Gerrit-Branch: master
Gerrit-Owner: MarkTraceur <[email protected]>
Gerrit-Reviewer: Cscott <[email protected]>
Gerrit-Reviewer: GWicke <[email protected]>
Gerrit-Reviewer: Subramanya Sastry <[email protected]>
Gerrit-Reviewer: jenkins-bot
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
