-
Notifications
You must be signed in to change notification settings - Fork 54
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move docs generations to bazel distribution (#393)
## What is the goal of this PR?
Moves bazel rules used for generating documentation into the
vaticle/bazel-distribution repository
## What are the changes implemented in this PR?
* Moves bazel rules & targets for converters of {doxygen, javadoc,
sphinx (python), rustdocs} into bazel-distribution. **Note:** nodejs
typedocs hasn't been migrated
PR chain: typedb/typedb-driver#552 > typedb/typedb-dependencies#491 >
#393- Loading branch information
1 parent
bc2fcd5
commit c63720a
Showing
13 changed files
with
540 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| # | ||
| # Copyright (C) 2022 Vaticle | ||
| # | ||
| # Licensed to the Apache Software Foundation (ASF) under one | ||
| # or more contributor license agreements. See the NOTICE file | ||
| # distributed with this work for additional information | ||
| # regarding copyright ownership. The ASF licenses this file | ||
| # to you under the Apache License, Version 2.0 (the | ||
| # "License"); you may not use this file except in compliance | ||
| # with the License. You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, | ||
| # software distributed under the License is distributed on an | ||
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| # KIND, either express or implied. See the License for the | ||
| # specific language governing permissions and limitations | ||
| # under the License. | ||
| # | ||
|
|
||
| exports_files(["cpp/doxyfile.template"]) | ||
|
|
||
| load("@bazel_skylib//:bzl_library.bzl", "bzl_library") | ||
| load("@vaticle_dependencies_tool_docs//:requirements.bzl", docs_requirement = "requirement") | ||
|
|
||
| py_binary( | ||
| name = "sphinx_runner", | ||
| srcs = [ | ||
| "python/sphinx_html_builder.py", | ||
| ], | ||
| main = "sphinx_html_builder.py", | ||
| deps = [docs_requirement("sphinx")], | ||
| visibility = ["//visibility:public"] | ||
| ) | ||
|
|
||
| bzl_library( | ||
| name = "lib", | ||
| srcs = [ | ||
| "cpp/rules.bzl", | ||
| "python/rules.bzl", | ||
| ], | ||
| deps = [], | ||
| visibility = ["//visibility:public"], | ||
| ) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| # Doxyfile 1.9.8 | ||
|
|
||
| # This file describes the settings to be used by the documentation system | ||
| # doxygen (www.doxygen.org) for a project. | ||
| # | ||
| # All text after a double hash (##) is considered a comment and is placed in | ||
| # front of the TAG it is preceding. | ||
| # | ||
| # All text after a single hash (#) is considered a comment and will be ignored. | ||
| # The format is: | ||
| # TAG = value [value, ...] | ||
| # For lists, items can also be appended using: | ||
| # TAG += value [value, ...] | ||
| # Values that contain spaces should be placed between quotes (\" \"). | ||
| #--------------------------------------------------------------------------- | ||
| # NOTE: | ||
| # This file has been cleaned up for doxygen doc generation via bazel | ||
| # To see all the options, generate a fresh one with | ||
| # `doxygen -g <output-path>` | ||
|
|
||
| #--------------------------------------------------------------------------- | ||
| # Project related configuration options | ||
| #--------------------------------------------------------------------------- | ||
| DOXYFILE_ENCODING = UTF-8 | ||
| PROJECT_NAME = ##{{PROJECT_NAME}} | ||
| PROJECT_NUMBER = ##{{PROJECT_NUMBER}} | ||
| PROJECT_BRIEF = ##{{PROJECT_BRIEF}} | ||
| OUTPUT_DIRECTORY = ##{{OUTPUT_DIRECTORY}} | ||
| CREATE_SUBDIRS = NO | ||
| ALLOW_UNICODE_NAMES = NO | ||
| OUTPUT_LANGUAGE = English | ||
|
|
||
| BRIEF_MEMBER_DESC = YES | ||
| ALWAYS_DETAILED_SEC = YES | ||
| REPEAT_BRIEF = YES | ||
| STRIP_FROM_PATH = ##{{STRIP_FROM_PATH}} | ||
| INHERIT_DOCS = YES | ||
| INLINE_INHERITED_MEMB = NO | ||
|
|
||
| MARKDOWN_SUPPORT = YES | ||
| AUTOLINK_SUPPORT = YES | ||
| FILE_PATTERNS = *.h *.hpp *.md *.html | ||
| CASE_SENSE_NAMES = NO | ||
|
|
||
| #--------------------------------------------------------------------------- | ||
| # Build related configuration options | ||
| #--------------------------------------------------------------------------- | ||
| HIDE_FRIEND_COMPOUNDS = YES | ||
| SHOW_HEADERFILE = NO ## Show which header to include | ||
| SHOW_INCLUDE_FILES = NO | ||
| SORT_BRIEF_DOCS = NO ## NO: The short description at the top is in declaration order | ||
| SORT_MEMBER_DOCS = YES ## YES: The longer description which follows is sorted alphabetically | ||
| SORT_BY_SCOPE_NAME = NO | ||
|
|
||
| #--------------------------------------------------------------------------- | ||
| # Configuration options related to warning and progress messages | ||
| #--------------------------------------------------------------------------- | ||
| QUIET = NO | ||
| WARNINGS = YES | ||
| WARN_IF_UNDOCUMENTED = YES | ||
| WARN_IF_DOC_ERROR = YES | ||
| WARN_IF_INCOMPLETE_DOC = YES | ||
| WARN_NO_PARAMDOC = YES | ||
| WARN_IF_UNDOC_ENUM_VAL = YES | ||
| WARN_AS_ERROR = NO | ||
|
|
||
| #--------------------------------------------------------------------------- | ||
| # Configuration options related to the input files | ||
| #--------------------------------------------------------------------------- | ||
| INPUT = ##{{INPUT}} | ||
| INPUT_ENCODING = UTF-8 | ||
| RECURSIVE = NO ## bazel explicitly specifies files | ||
| EXCLUDE_SYMLINKS = NO ## bazel needs NO | ||
| USE_MDFILE_AS_MAINPAGE = ##{{USE_MDFILE_AS_MAINPAGE}} | ||
| VERBATIM_HEADERS = YES | ||
|
|
||
| #--------------------------------------------------------------------------- | ||
| # Configuration options related to the alphabetical class index | ||
| #--------------------------------------------------------------------------- | ||
| ALPHABETICAL_INDEX = YES | ||
|
|
||
| #--------------------------------------------------------------------------- | ||
| # Configuration options related to the HTML output | ||
| #--------------------------------------------------------------------------- | ||
| GENERATE_HTML = YES | ||
| HTML_OUTPUT = html | ||
| HTML_FILE_EXTENSION = .html | ||
| HTML_COLORSTYLE = AUTO_LIGHT | ||
| ENUM_VALUES_PER_LINE = 4 | ||
| OBFUSCATE_EMAILS = YES | ||
| SEARCHENGINE = YES | ||
|
|
||
| GENERATE_LATEX = NO | ||
|
|
||
| #--------------------------------------------------------------------------- | ||
| # Configuration options related to diagram generator tools | ||
| #--------------------------------------------------------------------------- | ||
| HIDE_UNDOC_RELATIONS = YES | ||
| CLASS_GRAPH = YES | ||
| HAVE_DOT = NO ## Disables many details |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| # | ||
| # Copyright (C) 2022 Vaticle | ||
| # | ||
| # Licensed to the Apache Software Foundation (ASF) under one | ||
| # or more contributor license agreements. See the NOTICE file | ||
| # distributed with this work for additional information | ||
| # regarding copyright ownership. The ASF licenses this file | ||
| # to you under the Apache License, Version 2.0 (the | ||
| # "License"); you may not use this file except in compliance | ||
| # with the License. You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, | ||
| # software distributed under the License is distributed on an | ||
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| # KIND, either express or implied. See the License for the | ||
| # specific language governing permissions and limitations | ||
| # under the License. | ||
| # | ||
|
|
||
| def _doxygen_docs_impl(ctx): | ||
| output_directory = ctx.actions.declare_directory(ctx.attr._output_directory) | ||
| files = [] | ||
| for target in ctx.attr.sources: | ||
| files.extend(target.files.to_list()) | ||
|
|
||
| replacements = { | ||
| "PROJECT_NAME": ctx.attr.project_name, | ||
| "PROJECT_NUMBER" : ctx.attr.version, | ||
| "PROJECT_BRIEF" : ctx.attr.desc, | ||
| "OUTPUT_DIRECTORY" : output_directory.path, | ||
| "STRIP_FROM_PATH": ctx.attr.strip_prefix, | ||
| } | ||
| if ctx.file.main_page_md != None: | ||
| files.append(ctx.file.main_page_md) | ||
| replacements["USE_MDFILE_AS_MAINPAGE"] = ctx.file.main_page_md.path | ||
|
|
||
| replacements["INPUT"] = " ".join([f.path for f in files]) | ||
|
|
||
| # Prepare doxyfile | ||
| doxyfile = ctx.actions.declare_file("%s.doxyfile" % ctx.attr.name) | ||
| ctx.actions.expand_template( | ||
| template = ctx.file._doxyfile_template, | ||
| output = doxyfile, | ||
| substitutions = {"##{{%s}}"%k : replacements[k] for k in replacements} | ||
| ) | ||
|
|
||
| files = [doxyfile] + files | ||
| print(doxyfile.path) | ||
| ctx.actions.run( | ||
| inputs = files, | ||
| outputs = [output_directory], | ||
| arguments = [doxyfile.path], | ||
| executable = "doxygen", | ||
| use_default_shell_env = True | ||
| ) | ||
|
|
||
| return DefaultInfo(files = depset([output_directory])) | ||
|
|
||
| doxygen_docs = rule( | ||
| implementation = _doxygen_docs_impl, | ||
| test = False, | ||
| attrs = { | ||
| "project_name" : attr.string( | ||
| doc = "The project name for the doxygen docs", | ||
| mandatory = True, | ||
| ), | ||
| "version" : attr.string( | ||
| doc = "The version of the project being documented", | ||
| default = "" | ||
| ), | ||
| "desc" : attr.string( | ||
| doc = "A description for the project", | ||
| default = "" | ||
| ), | ||
| "sources" : attr.label_list( | ||
| doc = "A list of files made available to doxygen. This is NOT automatically included in the doxyfile", | ||
| mandatory = True, | ||
| allow_files = True, | ||
| ), | ||
| "strip_prefix" : attr.string( | ||
| doc = "Prefix to strip from path of files being processed", | ||
| default = "" | ||
| ), | ||
| "main_page_md" : attr.label( | ||
| doc = "The file to use as main page for the generate docs", | ||
| allow_single_file = True, | ||
| mandatory = False | ||
| ), | ||
| "_doxyfile_template" : attr.label( | ||
| allow_single_file = True, | ||
| default = "//docs:cpp/doxyfile.template" | ||
| ), | ||
| "_output_directory" : attr.string( | ||
| doc = "The output directory for the doxygen docs", | ||
| default = "doxygen_docs" | ||
| ) | ||
| }, | ||
| doc = """ | ||
| Creates HTML documentation for C++ projects using Doxygen. | ||
| This rule is not hermetic, and requires doxygen to be installed on the host. | ||
| """ | ||
| ) |
Oops, something went wrong.