Merge pull request #168 from mull-project/focused-itest

docs: create "Extra features" section, add a task to generate docs

docs/01-what-is-filecheck.rst

@@ -28,7 +28,7 @@ possible to keep third-party binary artifacts in source code
 https://github.com/doorstop-dev/doorstop/pull/431#issuecomment-549237579).
 
 **Note:** FileCheck.py is not intended to be a replacement for LLVM's FileCheck
-in any way. See :doc:`07-roadmap`.
+in any way. See :ref:`roadmap`.
 
 What's next?
 ------------
@@ -38,7 +38,7 @@ to read the tutorials: :doc:`03-tutorial-hello-world` and
 :doc:`04-tutorial-lit-and-filecheck`.
 
 If you know how FileCheck and LIT work, you can check out the status of the port
-on the :doc:`07-roadmap` page.
+on the :ref:`roadmap` page.
 
 Links
 -----

docs/05-check-commands.rst

@@ -175,13 +175,3 @@ If the empty line is removed, the test will fail:
     ^
     $ echo $?
     1
-
-Line number expression
-======================
-
-It is often useful to check for a specific line number in your regular
-expression, relative to its location in the file. Hard-coding that number can
-make the test fragile -- rearranging, adding, or deleting lines requires
-changing the expression. To solve this, FileCheck supports a variable for the
-current line number, `[[# @LINE ]]`, as well as simple offsets from this
-variable, e.g. `[[# @LINE + 4 ]]` or `[[# @LINE - 2 ]]`.

docs/07-extra-features.rst

@@ -0,0 +1,31 @@
+Extra features from LLVM FileCheck
+==================================
+
+Line number expression
+----------------------
+
+It is often useful to check for a specific line number in your regular
+expression, relative to its location in the file. Hard-coding that number can
+make the test fragile -- rearranging, adding, or deleting lines requires
+changing the expression. To solve this, FileCheck supports a variable for the
+current line number, ``[[# @LINE ]]``, as well as simple offsets from this
+variable, e.g. ``[[# @LINE + 4 ]]`` or ``[[# @LINE - 2 ]]``.
+
+Example:
+
+.. code-block:: c
+
+    /**
+    RUN: gcc "%s" -o %S/line && %S/line | filecheck %s
+    */
+
+    #include <stdio.h>
+    int main() {
+      // CHECK: Hello from line [[# @LINE + 1 ]]
+      printf("Hello from line %d\n", __LINE__);
+      return 0;
+    }
+
+See also
+`LLVM FileCheck documentation for this feature
+<https://llvm.org/docs/CommandGuide/FileCheck.html#filecheck-pseudo-numeric-variables>`_.

docs/07-roadmap.rst → docs/08-roadmap.rst

@@ -1,3 +1,5 @@
+.. _roadmap:
+
 Roadmap
 =======
 

docs/conf.py

@@ -62,6 +62,6 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 master_doc = 'index'
 

docs/index.rst

@@ -10,8 +10,9 @@ Welcome to FileCheck.py's documentation!
    04-tutorial-lit-and-filecheck
    05-check-commands
    06-options
-   07-roadmap
-   08-known-issues
+   07-extra-features
+   08-roadmap
+   09-known-issues
 
 .. Indices and tables
    ==================

tasks.py

@@ -127,6 +127,20 @@ def clean(c):
     c.run("{}".format(echo_command))
 
 
+@task
+def docs_sphinx(c, open=False):
+    command = formatted_command("""
+        cd docs && make html SPHINXOPTS="-W --keep-going -n"
+    """)
+    c.run(command)
+    if open:
+        c.run(
+            formatted_command("""
+                open docs/_build/html/index.html
+            """)
+        )
+
+
 # https://github.com/github-changelog-generator/github-changelog-generator
 # gem install github_changelog_generator
 @task