docs: include changelog and contributing page in generated docs. (#1617) This better unifies where docs can be viewed. Also deletes some mentions of having to generate the docs manually.
diff --git a/BUILD.bazel b/BUILD.bazel index 8dd2242..007e524 100644 --- a/BUILD.bazel +++ b/BUILD.bazel
@@ -24,6 +24,11 @@ "version.bzl", ]) +exports_files( + glob(["*.md"]), + visibility = ["//docs:__subpackages__"], +) + filegroup( name = "distribution", srcs = [
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf3a496..c6532d9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md
@@ -65,10 +65,6 @@ them are slow. If you're working on a particular area of code, you can run just the tests in those directories instead, which can speed up your edit-run cycle. -Note that there are tests to verify generated documentation is correct -- if -you're modifying the signature of a public function, these tests will likely -fail and you'll need to [regenerate the api docs](#documentation). - ## Formatting Starlark files should be formatted by @@ -150,17 +146,6 @@ Some checked-in files are generated and need to be updated when a new PR is merged. -### Documentation - -To regenerate the content under the `docs/` directory, run this command: - -```shell -bazel run //docs:update -``` - -This needs to be done whenever the docstrings in the corresponding .bzl files -are changed; a test failure will remind you to run this command when needed. - ## Core rules The bulk of this repo is owned and maintained by the Bazel Python community.
diff --git a/docs/sphinx/BUILD.bazel b/docs/sphinx/BUILD.bazel index 832a58e..95b3cfa 100644 --- a/docs/sphinx/BUILD.bazel +++ b/docs/sphinx/BUILD.bazel
@@ -55,6 +55,10 @@ formats = [ "html", ], + renamed_srcs = { + "//:CHANGELOG.md": "changelog.md", + "//:CONTRIBUTING.md": "contributing.md", + }, sphinx = ":sphinx-build", strip_prefix = package_name() + "/", tags = ["docs"],
diff --git a/docs/sphinx/index.md b/docs/sphinx/index.md index a84dab5..bec652a 100644 --- a/docs/sphinx/index.md +++ b/docs/sphinx/index.md
@@ -60,6 +60,8 @@ pip coverage gazelle +Contributing <contributing> +Changelog <changelog> api/index glossary genindex
diff --git a/sphinxdocs/private/sphinx.bzl b/sphinxdocs/private/sphinx.bzl index 8b3244b..daff02d 100644 --- a/sphinxdocs/private/sphinx.bzl +++ b/sphinxdocs/private/sphinx.bzl
@@ -45,7 +45,17 @@ **kwargs ) -def sphinx_docs(name, *, srcs = [], sphinx, config, formats, strip_prefix = "", extra_opts = [], **kwargs): +def sphinx_docs( + name, + *, + srcs = [], + renamed_srcs = {}, + sphinx, + config, + formats, + strip_prefix = "", + extra_opts = [], + **kwargs): """Generate docs using Sphinx. This generates three public targets: @@ -62,6 +72,9 @@ Args: name: (str) name of the docs rule. srcs: (label list) The source files for Sphinx to process. + renamed_srcs: (label_keyed_string_dict) Doc source files for Sphinx that + are renamed. This is typically used for files elsewhere, such as top + level files in the repo. sphinx: (label) the Sphinx tool to use for building documentation. Because Sphinx supports various plugins, you must construct your own binary with the necessary dependencies. The @@ -83,6 +96,7 @@ _sphinx_docs( name = name, srcs = srcs, + renamed_srcs = renamed_srcs, sphinx = sphinx, config = config, formats = formats, @@ -143,6 +157,12 @@ "other options, but before the source/output args.", ), "formats": attr.string_list(doc = "Output formats for Sphinx to create."), + "renamed_srcs": attr.label_keyed_string_dict( + allow_files = True, + doc = "Doc source files for Sphinx that are renamed. This is " + + "typically used for files elsewhere, such as top level " + + "files in the repo.", + ), "sphinx": attr.label( executable = True, cfg = "exec", @@ -189,6 +209,23 @@ for orig_file in ctx.files.srcs: _symlink_source(orig_file) + for src_target, dest in ctx.attr.renamed_srcs.items(): + src_files = src_target.files.to_list() + if len(src_files) != 1: + fail("A single file must be specified to be renamed. Target {} " + + "generate {} files: {}".format( + src_target, + len(src_files), + src_files, + )) + sphinx_src = ctx.actions.declare_file(paths.join(source_prefix, dest)) + ctx.actions.symlink( + output = sphinx_src, + target_file = src_files[0], + progress_message = "Symlinking (renamed) Sphinx source %{input} to %{output}", + ) + sphinx_source_files.append(sphinx_src) + return sphinx_source_dir_path, source_conf_file, sphinx_source_files def _run_sphinx(ctx, format, source_path, inputs, output_prefix):