Misc docs improvements

rules-proto-grpc · Apr 7, 2021 · a6a8578 · a6a8578 · alexeagle · Jun 6, 2021
1 parent 5a297e8
commit a6a8578
Show file tree

Hide file tree

Showing 14 changed files with 124 additions and 106 deletions.
diff --git a/docs/example.rst b/docs/example.rst
@@ -6,21 +6,24 @@
 Example Usage
 =============
 
-These steps walk through the actions required to go from a raw ``.proto`` file to a C++ library. Other languages will have
-a similar high-level layout, but you should check the language specific pages too.
+These steps walk through the actions required to go from a raw ``.proto`` file to a C++ library.
+Other languages will have a similar high-level layout, but you should check the language specific
+pages too.
 
 
-**Step 1**: Install rules_proto_grpc
+**Step 1**: Load rules_proto_grpc
 ------------------------------------
 
-First, follow the instructions to install the rules_proto_grpc rules :ref:`here <sec_installation>`
+First, follow :ref:`the instructions <sec_installation>` to load the rules_proto_grpc rules in your
+``WORKSPACE`` file.
 
 
 **Step 2**: Write a ``.proto`` file
 -----------------------------------
 
-Write a protobuf ``.proto file``, following `the specification <https://developers.google.com/protocol-buffers/docs/proto3>`__.
-In this case, we've called the file ``thing.proto``.
+Write a protobuf ``.proto file``, following
+`the specification <https://developers.google.com/protocol-buffers/docs/proto3>`__. In this case,
+we've called the file ``thing.proto``.
 
 .. code-block:: proto
 
@@ -49,19 +52,19 @@ This file should introduce a `proto_library <https://docs.bazel.build/versions/m
        deps = ["@com_google_protobuf//:any_proto"],
    )
 
-This rule takes no visible action, but is used to group a set of related ``.proto`` files and their dependencies.
-In this example we have a dependency on a well-known type ``any.proto``, hence the ``proto_library`` to ``proto_library``
-dependency (``"@com_google_protobuf//:any_proto"``)
+This rule takes no visible action, but is used to group a set of related ``.proto`` files and their
+dependencies. In this example we have a dependency on a well-known type ``any.proto``, hence the
+``proto_library`` to ``proto_library`` dependency (``"@com_google_protobuf//:any_proto"``)
 
 
 **Step 4**: Add a ``cpp_proto_compile`` target
 ----------------------------------------------
 
-We now add a target using the ``cpp_proto_compile`` rule. This rule converts our ``.proto`` file into the
-C++ specific ``.h`` and ``.cc`` files.
+We now add a target using the ``cpp_proto_compile`` rule. This rule converts our ``.proto`` file
+into the C++ specific ``.h`` and ``.cc`` files.
 
-**Note**: In this example ``thing.proto`` does not include service definitions (gRPC). For protos with services, use the
-``cpp_grpc_compile`` rule instead.
+.. note:: In this example ``thing.proto`` does not include service definitions (gRPC). For protos
+   with services, use the ``cpp_grpc_compile`` rule instead.
 
 .. code-block:: python
 
@@ -77,8 +80,8 @@ C++ specific ``.h`` and ``.cc`` files.
 **Step 5**: Load the ``WORKSPACE`` macro
 ----------------------------------------
 
-But wait, before we can build this, we need to load the dependencies necessary for this rule in our ``WORKSPACE``.
-(see :ref:`cpp_proto_compile`):
+But wait, before we can build this, we need to load the dependencies necessary for this rule in our
+``WORKSPACE`` (see :ref:`cpp_proto_compile`):
 
 .. code-block:: python
 
@@ -106,9 +109,10 @@ You should now see generated ``.cc`` and ``.h`` files in your bazel-bin output t
 **Step 7**: Create a library
 ----------------------------
 
-If we were only interested in the generated files, the ``cpp_grpc_compile`` rule would be fine. However, for
-convenience we'd rather have the outputs compiled into a C++ library with the necessary dependencies
-linked. To do that, let's change the  rule from ``cpp_proto_compile`` to ``cpp_proto_library``:
+If we were only interested in the generated files, the ``cpp_grpc_compile`` rule would be fine.
+However, for convenience we'd rather have the outputs compiled into a C++ library with the necessary
+dependencies linked. To do that, let's change the  rule from ``cpp_proto_compile`` to
+``cpp_proto_library``:
 
 .. code-block:: python
 
@@ -131,8 +135,10 @@ Now we can build again:
      bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.h
      bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.cc
 
-This time, we also have ``.a`` and ``.so`` files built. We can now use ``//example/proto:cpp_thing_proto`` as a dependency of
-any other ``cc_library`` or ``cc_binary`` target as per normal.
+This time, we also have ``.a`` and ``.so`` files built. We can now use
+``//example/proto:cpp_thing_proto`` as a dependency of any other ``cc_library`` or ``cc_binary``
+target as per normal.
 
-**Note**: The ``cpp_proto_library`` target implicitly calls ``cpp_proto_compile``, and we can access that rule's by adding
-``_pb`` at the end of the target name, like ``bazel build //example/proto:cpp_thing_proto_pb``
+.. note:: The ``cpp_proto_library`` target implicitly calls ``cpp_proto_compile``, and we can access
+   that rule's by adding ``_pb`` at the end of the target name, like
+   ``bazel build //example/proto:cpp_thing_proto_pb``
diff --git a/docs/index.rst b/docs/index.rst
@@ -8,7 +8,8 @@ Protobuf and gRPC rules for `Bazel <https://bazel.build>`_
 
 `Bazel <https://bazel.build>`_ rules for building `Protobuf <https://developers.google.com/protocol-buffers>`_
 and `gRPC <https://grpc.io>`_ code and libraries from
-`proto_library <https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library>`_ targets
+`proto_library <https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library>`_
+targets
 
 .. image:: https://img.shields.io/github/v/tag/rules-proto-grpc/rules_proto_grpc?label=release&sort=semver&color=38a3a5
    :alt: Latest Release
@@ -30,37 +31,49 @@ and `gRPC <https://grpc.io>`_ code and libraries from
 Overview
 --------
 
-These rules provide `Protocol Buffers (Protobuf) <https://developers.google.com/protocol-buffers>`_ and
-`gRPC <https://grpc.io>`_ rules for a range of languages and services.
+These rules provide `Protocol Buffers (Protobuf) <https://developers.google.com/protocol-buffers>`_
+and `gRPC <https://grpc.io>`_ rules for a range of languages and services within Bazel. This
+includes generation of language specific files from protoc and the creation of libraries from these
+files.
 
-Each supported language (``{lang}`` below) is generally split into four rule flavours:
+Each supported language (``{lang}`` below) is generally split into four rule types:
 
-- ``{lang}_proto_compile``: Provides generated files from the Protobuf `protoc` plugin for the language. e.g for C++ this
-  provides the generated ``*.pb.cc`` and ``*.pb.h`` files.
+- ``{lang}_proto_compile``: Provides generated files from the Protobuf `protoc` plugin for the
+  language. For example, for C++ this provides the generated ``*.pb.cc`` and ``*.pb.h`` files.
 
-- ``{lang}_proto_library``: Provides a language-specific library from the generated Protobuf ``protoc`` plugin outputs,
-  along with necessary dependencies. e.g for C++ this provides a Bazel native ``cpp_library`` created  from the generated
-  ``*.pb.cc`` and ``*.pb.h`` files, with the Protobuf library linked. For languages that do not have a 'library' concept,
-  this rule may not exist.
+- ``{lang}_proto_library``: Provides a language-specific library from the generated Protobuf
+  ``protoc`` plugin outputs, along with necessary dependencies. For example, for C++ this provides a
+  Bazel native ``cpp_library`` created  from the generated ``*.pb.cc`` and ``*.pb.h`` files, with
+  the Protobuf library linked.
 
-- ``{lang}_grpc_compile``: Provides generated files from both the Protobuf and gRPC ``protoc`` plugins for the language.
-  e.g for C++ this provides the generated ``*.pb.cc``, ``*.grpc.pb.cc``, ``*.pb.h`` and ``*.grpc.pb.h`` files.
+- ``{lang}_grpc_compile``: Provides generated files from both the Protobuf and gRPC ``protoc``
+  plugins for the language. For example, for C++ this provides the generated ``*.pb.cc``,
+  ``*.grpc.pb.cc``, ``*.pb.h`` and ``*.grpc.pb.h`` files.
 
-- ``{lang}_grpc_library``: Provides a language-specific library from the generated Protobuf and gRPC ``protoc`` plugins
-  outputs, along with necessary dependencies. e.g for C++ this provides a Bazel native ``cpp_library`` created from the
-  generated ``*.pb.cc``, ``*.grpc.pb.cc``, ``*.pb.h`` and ``*.grpc.pb.h`` files, with the Protobuf and gRPC libraries linked.
-  For languages that do not have a 'library' concept, this rule may not exist.
+- ``{lang}_grpc_library``: Provides a language-specific library from the generated Protobuf and gRPC
+  ``protoc`` plugins outputs, along with necessary dependencies. For example, for C++ this provides
+  a Bazel native ``cpp_library`` created from the generated ``*.pb.cc``, ``*.grpc.pb.cc``,
+  ``*.pb.h`` and ``*.grpc.pb.h`` files, with the Protobuf and gRPC libraries linked.
 
-Therefore, if you are solely interested in the generated source code files, use the ``{lang}_{proto|grpc}_compile``
-rules. Otherwise, if you want a ready-to-go library, use the ``{lang}_{proto|grpc}_library`` rules.
+Some languages may have variations on these rules, such as when there are multiple gRPC or Protobuf
+implementations. However, generally you'll want to use the ``{lang}_{proto|grpc}_library`` rules,
+since these bundle up all the outputs into a library that can easily be used elsewhere in your Bazel
+project workspace. Alternatively, if you just want the generated source code files, use the
+``{lang}_{proto|grpc}_compile`` rules instead.
 
 
 .. _sec_installation:
 
 Installation
 ------------
 
-Add ``rules_proto_grpc`` to your ``WORKSPACE`` file and then look at the language specific examples linked below:
+Add ``rules_proto_grpc`` to your ``WORKSPACE`` file as shown below and then look at the language
+specific examples linked in the docs. It is recommended that you use the tagged releases for stable
+rules. Master is intended to be 'ready-to-use', but may be unstable at certain periods. To be
+notified of new releases, you can use GitHub's 'Watch Releases Only' on the repository.
+
+.. note:: You will also need to follow instructions in the language-specific pages for additional
+   workspace dependencies that may be required.
 
 .. code-block:: python
 
@@ -81,13 +94,6 @@ Add ``rules_proto_grpc`` to your ``WORKSPACE`` file and then look at the languag
    rules_proto_dependencies()
    rules_proto_toolchains()
 
-It is recommended that you use the tagged releases for stable rules. Master is intended to be 'ready-to-use', but may be
-unstable at certain periods. To be notified of new releases, you can use GitHub's 'Watch Releases Only' on the
-repository.
-
-**Note**: You will also need to follow instructions in the language-specific pages for additional workspace
-dependencies that may be required.
-
 
 .. toctree::
    :caption: General

diff --git a/docs/lang/buf.rst b/docs/lang/buf.rst
@@ -28,7 +28,7 @@ Only Linux and Darwin (MacOS) is currently supported by Buf.
 buf_proto_breaking_test
 -----------------------
 
-**Note**: This rule is experimental. It may not work correctly!
+.. warning:: This rule is experimental. It may not work correctly!
 
 Checks .proto files for breaking changes
 
@@ -112,7 +112,7 @@ Plugins
 buf_proto_lint_test
 -------------------
 
-**Note**: This rule is experimental. It may not work correctly!
+.. warning:: This rule is experimental. It may not work correctly!
 
 Lints .proto files
 

diff --git a/docs/lang/c.rst b/docs/lang/c.rst
@@ -24,7 +24,7 @@ Rules for generating C protobuf ``.c`` & ``.h`` files and libraries using `upb <
 c_proto_compile
 ---------------
 
-**Note**: This rule is experimental. It may not work correctly!
+.. warning:: This rule is experimental. It may not work correctly!
 
 Generates C protobuf ``.h`` & ``.c`` files
 
@@ -116,7 +116,7 @@ Plugins
 c_proto_library
 ---------------
 
-**Note**: This rule is experimental. It may not work correctly!
+.. warning:: This rule is experimental. It may not work correctly!
 
 Generates a C protobuf library using ``cc_library``, with dependencies linked
 

diff --git a/docs/lang/d.rst b/docs/lang/d.rst
@@ -8,7 +8,7 @@ D
 
 Rules for generating D protobuf ``.d`` files and libraries using `protobuf-d <https://github.com/dcarp/protobuf-d>`_. Libraries are created with ``d_library`` from `rules_d <https://github.com/bazelbuild/rules_d>`_
 
-**NOTE**: These rules use the protoc-gen-d plugin, which only supports proto3 .proto files.
+.. note:: These rules use the protoc-gen-d plugin, which only supports proto3 .proto files.
 
 .. list-table:: Rules
    :widths: 1 2

diff --git a/docs/lang/doc.rst b/docs/lang/doc.rst
@@ -28,7 +28,7 @@ Rules for generating protobuf Markdown, JSON, HTML or DocBook documentation with
 doc_docbook_compile
 -------------------
 
-**Note**: This rule is experimental. It may not work correctly!
+.. warning:: This rule is experimental. It may not work correctly!
 
 Generates DocBook ``.xml`` documentation file
 
@@ -116,7 +116,7 @@ Plugins
 doc_html_compile
 ----------------
 
-**Note**: This rule is experimental. It may not work correctly!
+.. warning:: This rule is experimental. It may not work correctly!
 
 Generates ``.html`` documentation file
 
@@ -204,7 +204,7 @@ Plugins
 doc_json_compile
 ----------------
 
-**Note**: This rule is experimental. It may not work correctly!
+.. warning:: This rule is experimental. It may not work correctly!
 
 Generates ``.json`` documentation file
 
@@ -292,7 +292,7 @@ Plugins
 doc_markdown_compile
 --------------------
 
-**Note**: This rule is experimental. It may not work correctly!
+.. warning:: This rule is experimental. It may not work correctly!
 
 Generates Markdown ``.md`` documentation file
 

diff --git a/docs/lang/js.rst b/docs/lang/js.rst
@@ -8,17 +8,17 @@ JavaScript
 
 Rules for generating JavaScript protobuf, gRPC-node and gRPC-Web ``.js`` and ``.d.ts`` files using standard Protocol Buffers and gRPC.
 
-**Note**: You must add the required dependencies to your package.json file:
+.. note:: You must add the required dependencies to your package.json file:
 
-.. code-block:: json
+   .. code-block:: json
 
-   "dependencies": {
-     "@grpc/grpc-js": "1.2.6",
-     "google-protobuf": "3.15.3",
-     "grpc-tools": "1.10.0",
-     "grpc-web": "1.2.1",
-     "ts-protoc-gen": "0.14.0"
-   }
+      "dependencies": {
+        "@grpc/grpc-js": "1.2.6",
+        "google-protobuf": "3.15.3",
+        "grpc-tools": "1.10.0",
+        "grpc-web": "1.2.1",
+        "ts-protoc-gen": "0.14.0"
+      }
 
 
 .. list-table:: Rules

diff --git a/docs/lang/objc.rst b/docs/lang/objc.rst
@@ -333,7 +333,7 @@ Attributes
 objc_grpc_library
 -----------------
 
-**Note**: This rule is experimental. It may not work correctly!
+.. warning:: This rule is experimental. It may not work correctly!
 
 Generates an Objective-C protobuf and gRPC library using ``objc_library``
 

diff --git a/docs/lang/python.rst b/docs/lang/python.rst
@@ -8,7 +8,7 @@ Python
 
 Rules for generating Python protobuf and gRPC ``.py`` files and libraries using standard Protocol Buffers and gRPC or `grpclib <https://github.com/vmagamedov/grpclib>`_. Libraries are created with ``py_library`` from ``rules_python``. To use the fast C++ Protobuf implementation, you can add ``--define=use_fast_cpp_protos=true`` to your build, but this requires you setup the path to your Python headers.
 
-**Note**: On Windows, the path to Python for ``pip_install`` may need updating to ``Python.exe``, depending on your install.
+.. note:: On Windows, the path to Python for ``pip_install`` may need updating to ``Python.exe``, depending on your install.
 
 .. list-table:: Rules
    :widths: 1 2

diff --git a/tools/rulegen/d.go b/tools/rulegen/d.go
@@ -41,7 +41,7 @@ func makeD() *Language {
 		DisplayName: "D",
 		Notes: mustTemplate("Rules for generating D protobuf ``.d`` files and libraries using `protobuf-d <https://github.com/dcarp/protobuf-d>`_. Libraries are created with ``d_library`` from `rules_d <https://github.com/bazelbuild/rules_d>`_" + `
 
-**NOTE**: These rules use the protoc-gen-d plugin, which only supports proto3 .proto files.`),
+.. note:: These rules use the protoc-gen-d plugin, which only supports proto3 .proto files.`),
 		Flags: commonLangFlags,
 		Rules: []*Rule{
 			&Rule{