Update docs

mooreryan · mooreryan · commit cda49b22a0fc · 2022-01-29T11:49:02.000-05:00
diff --git a/README.md b/README.md
@@ -63,6 +63,8 @@ $ dune exec ./run.exe
 
 For information on installing and using `pyml_bindgen`, check out the [docs](https://mooreryan.github.io/ocaml_python_bindgen/).
 
+Additionally, you can find examples in the [examples](https://github.com/mooreryan/ocaml_python_bindgen/tree/main/examples) directory.  One neat thing about these examples is that you can see how to write Dune [rules](https://dune.readthedocs.io/en/stable/dune-files.html#rule) to automatically generate your `pyml` bindings.
+
 ## License
 
 [![license MIT or Apache
diff --git a/_docs_src/mkdocs.yml b/_docs_src/mkdocs.yml
@@ -14,12 +14,14 @@ nav:
     - Handling Dictionaries 2: dictionaries-2.md
     - Recursive Classes: recursive.md
   - Rules:
+    - Overview: rules-overview.md
     - Types: types.md
     - Function & Argument Names: names.md
     - Attributes & Properties: attributes.md
     - Instance Methods: instance-methods.md
     - Class & Static Methods; Functions: static-methods.md
   - Miscellaneous:
+    - Auto-generating bindings: auto-gen-bindings.md
     - CLI Options: cli-options.md
     - Converting `pyobjects` to OCaml types: of-pyobject.md
     - Handling Tuples: tuples.md
diff --git a/_docs_src/src/auto-gen-bindings.md b/_docs_src/src/auto-gen-bindings.md
@@ -0,0 +1,7 @@
+# Automatically Generating Bindings
+
+Sometimes it can be a bit of a pain to always have to run `pyml_bindgen` by hand.
+
+One way to avoid this is by adding a [rule](https://dune.readthedocs.io/en/stable/dune-files.html#rule) to your Dune file.
+
+For an example of this, check out the `dune` file in the [quick start](https://github.com/mooreryan/ocaml_python_bindgen/tree/main/examples/quick_start) example on GitHub.  It has lots of comments to show you how it is working.
diff --git a/_docs_src/src/index.md b/_docs_src/src/index.md
@@ -47,6 +47,8 @@ $ pyml_bindgen --help
 
 ## Quick start
 
+*Note: You can find full examples in the [examples](https://github.com/mooreryan/ocaml_python_bindgen/tree/main/examples) directory on GitHub.  One neat thing about the examples there is that you can see how to write Dune [rules](https://dune.readthedocs.io/en/stable/dune-files.html#rule) to automatically generate your `pyml` bindings.*
+
 `pyml_bindgen` is a CLI program that generates OCaml modules that bind Python classes via [pyml](https://github.com/thierry-martinez/pyml).
 
 Here's a small example.  Take a Python class, `Thing`.  (Put it in a file called `thing.py`...this means the Python module will be called `thing`.)
diff --git a/_docs_src/src/rules-overview.md b/_docs_src/src/rules-overview.md
@@ -0,0 +1,5 @@
+# Rules Overview
+
+The following pages are an informal description of some of the rules you have to follow when using `pyml_bindgen`.
+
+I will try and keep them updated and (reasonably) complete.  However, if you really want to know how something is working, you may want to have a look at the [tests](https://github.com/mooreryan/ocaml_python_bindgen/tree/main/test).
diff --git a/examples/quick_start/README.md b/examples/quick_start/README.md
@@ -2,7 +2,7 @@
 
 This is a simple example where all files including the Python module that we want to bind are in a single directory.
 
-For more details about this example, see the [Quick Start](https://github.com/mooreryan/ocaml_python_bindgen#quick-start).
+For more details about this example, see the [Quick Start](https://github.com/mooreryan/ocaml_python_bindgen#quick-start).  There you will see an explanation of how to run `pyml_bindgen` to generate the bindings you see here.
 
 ## Files
 
@@ -16,12 +16,11 @@ For more details about this example, see the [Quick Start](https://github.com/mo
 
 `lib.ml` is the file of `pyml` bindings generated by `pyml_bindgen`.
 
-The `dune` file has a rule to automatically generate this file for you when you run `dune build` in the root of the repository.
+The `dune` file has a rule to automatically generate this file for you when you run `dune build` in the root of the repository.  Check out the `dune` file to see how to do this...it has lots of comments in there!
 
 However, if you wanted to make this file manually, you could do so like this:
 
 ```
 $ pyml_bindgen val_specs.txt adder Adder --caml-module Adder | \
      ocamlformat --name lib.ml -
 ```
-
diff --git a/examples/quick_start/dune b/examples/quick_start/dune
@@ -3,12 +3,27 @@
  (libraries pyml))
 
 (rule
+ ;; The file produced by this rule will be called `lib.ml`.
+ (target lib.ml)
+ ;; Put the resulting lib.ml file in this directory.  When you run
+ ;; `dune clean`, it will be removed.
  (mode
   (promote (until-clean)))
- (target lib.ml)
  (action
+  ;; `pyml_bindgen` outputs directly to stdout, so we need to redirect
+  ;; the stdout to `lib.ml`.  We do this using `with-stdout-to`.
   (with-stdout-to
+   ;; This is the name of the file to which the output of the
+   ;; following command will be directed.
    lib.ml
+   ;; This step isn't necessary, but I use `ocamlformat` for
+   ;; everything, so I would like to have the output of
+   ;; `pyml_bindgen` also processed by `ocamlformat`.  `pipe-stdout`
+   ;; takes the stdout of the first `run` command and pipes it to the
+   ;; stdin of the second `run` command.
    (pipe-stdout
+    ;; Here is the acutal `pyml_bindgen` command to generate the
+    ;; bindings.
     (run %{bin:pyml_bindgen} val_specs.txt adder Adder --caml-module Adder)
-    (run ocamlformat --name lib.ml --enable-outside-detected-project -)))))
+    ;; And finally, process the bindings code with ocamlformat.
+    (run ocamlformat --name lib.ml -)))))
