From c2502f45c9b26413174ab58395175eb5d169ce4d Mon Sep 17 00:00:00 2001 From: Mark Mentovai Date: Wed, 18 Mar 2015 17:10:12 -0400 Subject: [PATCH] doc: Add documentation-generating scripts to the Crashpad tree. R=rsesek@chromium.org Review URL: https://codereview.chromium.org/1009223003 --- crashpad.gyp | 2 +- doc/asciidoc.conf | 31 ++++++++ doc/asciidoc.css | 20 ++++++ crashpad.doxy => doc/crashpad.doxy | 7 +- crashpad.doxy.h => doc/crashpad.doxy.h | 0 doc/generate_asciidoc.sh | 98 ++++++++++++++++++++++++++ doc/generate_doxygen.sh | 29 ++++++++ {tools => doc}/man_footer.ad | 0 handler/mac/crashpad_handler.ad | 2 +- tools/generate_dump.ad | 2 +- tools/mac/catch_exception_tool.ad | 2 +- tools/mac/exception_port_tool.ad | 2 +- tools/mac/on_demand_service_tool.ad | 2 +- tools/mac/run_with_crashpad.ad | 2 +- 14 files changed, 188 insertions(+), 11 deletions(-) create mode 100644 doc/asciidoc.conf create mode 100644 doc/asciidoc.css rename crashpad.doxy => doc/crashpad.doxy (99%) rename crashpad.doxy.h => doc/crashpad.doxy.h (100%) create mode 100755 doc/generate_asciidoc.sh create mode 100755 doc/generate_doxygen.sh rename {tools => doc}/man_footer.ad (100%) diff --git a/crashpad.gyp b/crashpad.gyp index 63735f24..f0270a01 100644 --- a/crashpad.gyp +++ b/crashpad.gyp @@ -28,7 +28,7 @@ 'util/util.gyp:*', ], 'sources': [ - 'crashpad.doxy.h', + 'doc/crashpad.doxy.h', 'package.h', ], }, diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf new file mode 100644 index 00000000..85df624f --- /dev/null +++ b/doc/asciidoc.conf @@ -0,0 +1,31 @@ +# Copyright 2015 The Crashpad Authors. All rights reserved. +# +# Licensed 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. + +[miscellaneous] +# AsciiDoc uses \r\n by default. +newline=\n + +# The default AsciiDoc lang-en.conf uses docdate and doctime for the +# last-updated line in footer-text. These attributes are taken from the file’s +# mtime and cannot be overridden. For a git-based project, the date of the last +# revision is desirable, so change this to use revdate, an attribute that can be +# computed and passed in by the script that runs AsciiDoc. For man pages, use +# the mansource and manversion attributes instead of the hard-coded “Version” +# string and revnumber attribute, so that the version will appear as “Crashpad +# 0.7.0” as it does in “man” output. +ifdef::basebackend-html[] +[footer-text] +{mansource=Version} {manversion={revnumber}}{basebackend-xhtml11?
}{basebackend-xhtml11=
} +Last updated {revdate} +endif::basebackend-html[] diff --git a/doc/asciidoc.css b/doc/asciidoc.css new file mode 100644 index 00000000..9808c216 --- /dev/null +++ b/doc/asciidoc.css @@ -0,0 +1,20 @@ +/* Copyright 2015 The Crashpad Authors. All rights reserved. + * + * Licensed 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. */ + +/* The default AsciiDoc asciidoc.css specifies fuchsia as the visited link + * color. This has a dated appearance. Replace it with blue, the same color used + * for unvisited links. */ +a:visited { + color: blue; +} diff --git a/crashpad.doxy b/doc/crashpad.doxy similarity index 99% rename from crashpad.doxy rename to doc/crashpad.doxy index d02ad211..16f9ed57 100644 --- a/crashpad.doxy +++ b/doc/crashpad.doxy @@ -58,7 +58,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = out +OUTPUT_DIRECTORY = out/doc/doxygen # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -799,8 +799,7 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = out \ - third_party +EXCLUDE = third_party # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -816,7 +815,7 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = out* # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the diff --git a/crashpad.doxy.h b/doc/crashpad.doxy.h similarity index 100% rename from crashpad.doxy.h rename to doc/crashpad.doxy.h diff --git a/doc/generate_asciidoc.sh b/doc/generate_asciidoc.sh new file mode 100755 index 00000000..55113b65 --- /dev/null +++ b/doc/generate_asciidoc.sh @@ -0,0 +1,98 @@ +#!/bin/bash + +# Copyright 2015 The Crashpad Authors. All rights reserved. +# +# Licensed 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. + +set -e + +# Generating AsciiDoc documentation requires AsciiDoc, +# http://www.methods.co.nz/asciidoc/. For “man” and PDF output, a DocBook +# toolchain including docbook-xml and docbook-xsl is also required. + +# Run from the Crashpad project root directory. +cd "$(dirname "${0}")/.." + +output_dir=out/doc/man + +rm -rf "${output_dir}" +mkdir -p \ + "${output_dir}/html" \ + "${output_dir}/man" + +# Some extensions of command-line tools behave differently on different systems. +# $sed_ext should be a sed invocation that enables extended regular expressions. +# $date_time_t should be a date invocation that causes it to print the date and +# time corresponding to a time_t string that immediately follows it. +uname_s="$(uname -s)" +case "${uname_s}" in + Darwin) + sed_ext="sed -E" + date_time_t="date -r" + ;; + Linux) + sed_ext="sed -r" + date_time_t="date -d@" + ;; + *) + echo "${0}: unknown operating system" >& 2 + exit 1 + ;; +esac + +# Get the version from package.h. +version=$(${sed_ext} -n -e 's/^#define PACKAGE_VERSION "(.*)"$/\1/p' package.h) + +for input in \ + handler/mac/crashpad_handler.ad \ + tools/*.ad \ + tools/mac/*.ad; do + echo "${input}" + + base=$(${sed_ext} -e 's%^.*/([^/]+)\.ad$%\1%' <<< "${input}") + + # Get the last-modified date of $input according to Git, in UTC. + git_time_t="$(git log -1 --format=%at "${input}")" + git_date="$(LC_ALL=C ${date_time_t}"${git_time_t}" -u '+%B %-d, %Y')" + + # Create HTML output. + asciidoc \ + --attribute mansource=Crashpad \ + --attribute manversion="${version}" \ + --attribute manmanual="Crashpad Manual" \ + --attribute revdate="${git_date}" \ + --conf-file doc/asciidoc.conf \ + --doctype manpage \ + --backend html5 \ + --attribute stylesheet="${PWD}/doc/asciidoc.css" \ + --out-file "${output_dir}/html/${base}.html" \ + "${input}" + + # Create “man” output. + # + # AsciiDoc 8.6.9 produces harmless incorrect warnings each time this is run: + # “a2x: WARNING: --destination-dir option is only applicable to HTML based + # outputs”. https://github.com/asciidoc/asciidoc/issues/44 + a2x \ + --attribute mansource=Crashpad \ + --attribute manversion="${version}" \ + --attribute manmanual="Crashpad Manual" \ + --attribute revdate="${git_date}" \ + --doctype manpage \ + --format manpage \ + --destination-dir "${output_dir}/man" \ + "${input}" + + # For PDF output, use an a2x command like the one above, with these options: + # --format pdf --fop --destination-dir "${output_dir}/pdf" +done diff --git a/doc/generate_doxygen.sh b/doc/generate_doxygen.sh new file mode 100755 index 00000000..5da9cd31 --- /dev/null +++ b/doc/generate_doxygen.sh @@ -0,0 +1,29 @@ +#!/bin/sh + +# Copyright 2015 The Crashpad Authors. All rights reserved. +# +# Licensed 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. + +set -e + +# Generating Doxygen documentation requires Doxygen, http://www.doxygen.org/. + +# Run from the Crashpad project root directory. +cd "$(dirname "${0}")/.." + +output_dir=out/doc/doxygen + +rm -rf "${output_dir}" +mkdir -p "${output_dir}" + +doxygen doc/crashpad.doxy diff --git a/tools/man_footer.ad b/doc/man_footer.ad similarity index 100% rename from tools/man_footer.ad rename to doc/man_footer.ad diff --git a/handler/mac/crashpad_handler.ad b/handler/mac/crashpad_handler.ad index 0b2b23f0..068dd482 100644 --- a/handler/mac/crashpad_handler.ad +++ b/handler/mac/crashpad_handler.ad @@ -64,4 +64,4 @@ catch_exception_tool(1), generate_dump(1), run_with_crashpad(1) -include::../../tools/man_footer.ad[] +include::../../doc/man_footer.ad[] diff --git a/tools/generate_dump.ad b/tools/generate_dump.ad index 36b14d5f..8c6d23b3 100644 --- a/tools/generate_dump.ad +++ b/tools/generate_dump.ad @@ -93,4 +93,4 @@ Failure, with a message printed to the standard error stream. catch_exception_tool(1) -include::man_footer.ad[] +include::../doc/man_footer.ad[] diff --git a/tools/mac/catch_exception_tool.ad b/tools/mac/catch_exception_tool.ad index 3b437845..0d9520ce 100644 --- a/tools/mac/catch_exception_tool.ad +++ b/tools/mac/catch_exception_tool.ad @@ -114,4 +114,4 @@ Failure, with a message printed to the standard error stream. exception_port_tool(1), on_demand_service_tool(1) -include::../man_footer.ad[] +include::../../doc/man_footer.ad[] diff --git a/tools/mac/exception_port_tool.ad b/tools/mac/exception_port_tool.ad index a0d7ca36..3cd8e9c9 100644 --- a/tools/mac/exception_port_tool.ad +++ b/tools/mac/exception_port_tool.ad @@ -185,4 +185,4 @@ The program specified by 'COMMAND' could not be found. catch_exception_tool(1), on_demand_service_tool(1) -include::../man_footer.ad[] +include::../../doc/man_footer.ad[] diff --git a/tools/mac/on_demand_service_tool.ad b/tools/mac/on_demand_service_tool.ad index 8bf596c9..54eb3693 100644 --- a/tools/mac/on_demand_service_tool.ad +++ b/tools/mac/on_demand_service_tool.ad @@ -99,4 +99,4 @@ exception_port_tool(1), launchctl(1) on_demand_service_tool(1) -include::../man_footer.ad[] +include::../../doc/man_footer.ad[] diff --git a/tools/mac/run_with_crashpad.ad b/tools/mac/run_with_crashpad.ad index 91a86455..51461938 100644 --- a/tools/mac/run_with_crashpad.ad +++ b/tools/mac/run_with_crashpad.ad @@ -109,4 +109,4 @@ The program specified by 'COMMAND' could not be found. crashpad_handler(8), exception_port_tool(1) -include::../man_footer.ad[] +include::../../doc/man_footer.ad[]