Merge pull request #1332 from pygments/task/improve-docs

Improve docs.

2 files changed, 54 insertions, 9 deletions

diff --git a/Contributing.md b/Contributing.md
new file mode 100644
index 00000000..b66ba717
--- /dev/null
+++ b/Contributing.md
@@ -0,0 +1,44 @@
+Licensing
+=========
+
+The code is distributed under the BSD 2-clause license. Contributors making pull
+requests must agree that they are able and willing to put their contributions
+under that license.
+
+Contribution checklist
+======================
+
+* Check the documentation for how to write
+  [a new lexer](https://pygments.org/docs/lexerdevelopment/),
+  [a new formatter](https://pygments.org/docs/formatterdevelopment/) or
+  [a new filter](https://pygments.org/docs/filterdevelopment/)
+* When writing rules, try to merge simple rules. For instance, combine:
+
+  ```python
+  _PUNCTUATION = [
+    (r"\(", token.Punctuation),
+    (r"\)", token.Punctuation),
+    (r"\[", token.Punctuation),
+    (r"\]", token.Punctuation),
+    ("{", token.Punctuation),
+    ("}", token.Punctuation),
+  ]
+  ```
+
+  into:
+
+  ```python
+  (r"[\(\)\[\]{}]", token.Punctuation)
+  ```
+* Be careful with ``.*``. This matches greedily as much as it can. For instance,
+  rule like ``@.*@`` will match the whole string ``@first@ second @third@``,
+  instead of matching ``@first@`` and ``@second@``. You can use ``@.*?@`` in
+  this case to stop early. The ``?`` tries to match _as few times_ as possible.
+* Don't add imports of your lexer anywhere in the codebase. (In case you're
+  curious about ``compiled.py`` -- this file exists for backwards compatibility
+  reasons.)
+* Use the standard importing convention: ``from token import Punctuation``
+* If you have a tricky case, you can use the ``testcase`` formatter to produce
+  an unit test quickly. Run 
+  ``python -m pygments -l lua -f testcase <<< "local a = 5"``. This will
+  produce a test case function skeleton.
\ No newline at end of file
diff --git a/doc/docs/lexerdevelopment.rst b/doc/docs/lexerdevelopment.rst
index 5b6813fb..530d8c15 100644
--- a/doc/docs/lexerdevelopment.rst
+++ b/doc/docs/lexerdevelopment.rst
@@ -106,13 +106,13 @@ flag ``-x``:
 
 .. code-block:: console
 
-    $ pygmentize -l your_lexer_file.py -x
+    $ python -m pygments -l your_lexer_file.py -x
 
 To specify a class name other than CustomLexer, append it with a colon:
 
 .. code-block:: console
 
-    $ pygmentize -l your_lexer.py:SomeLexer -x
+    $ python -m pygments -l your_lexer.py:SomeLexer -x
 
 Or, using the Python API:
 
@@ -140,7 +140,7 @@ cloned from GitHub.
 
 .. code-block:: console
 
-    $ cd .../pygments-main
+    $ cd pygments
 
 Select a matching module under ``pygments/lexers``, or create a new module for
 your lexer class.
@@ -164,16 +164,17 @@ To test the new lexer, store an example file with the proper extension in
 ``tests/examplefiles``.  For example, to test your ``DiffLexer``, add a
 ``tests/examplefiles/example.diff`` containing a sample diff output.
 
-Now you can use pygmentize to render your example to HTML:
+Now you can use ``python -m pygments`` from the current root of the checkout to
+render your example to HTML:
 
 .. code-block:: console
 
-    $ ./pygmentize -O full -f html -o /tmp/example.html tests/examplefiles/example.diff
+    $ python -m pygments -O full -f html -o /tmp/example.html tests/examplefiles/example.diff
 
-Note that this explicitly calls the ``pygmentize`` in the current directory
-by preceding it with ``./``. This ensures your modifications are used.
-Otherwise a possibly already installed, unmodified version without your new
-lexer would have been called from the system search path (``$PATH``).
+Note that this explicitly calls the ``pygments`` module in the current
+directory. This ensures your modifications are used. Otherwise a possibly
+already installed, unmodified version without your new lexer would have been
+called from the system search path (``$PATH``).
 
 To view the result, open ``/tmp/example.html`` in your browser.