This is an automated email from the ASF dual-hosted git repository. aw pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/yetus.git
The following commit(s) were added to refs/heads/master by this push: new 8acb2ba YETUS-431. shelldocs is undocumented 8acb2ba is described below commit 8acb2ba5538d9df1b1732775bc2818ebc335653b Author: Allen Wittenauer <a...@apache.org> AuthorDate: Fri Apr 5 09:52:33 2019 -0700 YETUS-431. shelldocs is undocumented Signed-off-by: Allen Wittenauer <a...@apache.org> --- .../source/documentation/in-progress.html.md | 19 +-- .../documentation/in-progress/releasedocmaker.md | 4 +- .../source/documentation/in-progress/shelldocs.md | 141 +++++++++++++++++++++ .../in-progress/yetus-maven-plugin.md | 35 ++++- 4 files changed, 180 insertions(+), 19 deletions(-) diff --git a/asf-site-src/source/documentation/in-progress.html.md b/asf-site-src/source/documentation/in-progress.html.md index 1e10d56..ade8f67 100644 --- a/asf-site-src/source/documentation/in-progress.html.md +++ b/asf-site-src/source/documentation/in-progress.html.md @@ -41,22 +41,9 @@ documenation [here](releasedocmaker). See also the [yetus-maven-plugin](#yetus-m Shelldocs provides generation of html formatted api documentation based on comments on Bash functions. Currently supports documenting API status (public / private) as well as parameters and return values. -See the shelldocs cli help for more information on usage. - -```bash -$ ./shelldocs/shelldocs.py --help -Usage: shelldocs.py --skipprnorep --output OUTFILE --input INFILE [--input INFILE ...] - -Options: - -h, --help show this help message and exit - -o OUTFILE, --output=OUTFILE - file to create - -i INFILE, --input=INFILE - file to read - --skipprnorep Skip Private & Not Replaceable -``` - -You can mark a file to be ignored by shelldocs by adding "SHELLDOC-IGNORE" as a comment in its own line. +See the [shelldocs page](shelldocs) for more information on usage. + +See also the [yetus-maven-plugin](#yetus-maven-plugin) for Apache Maven-specific information. # yetus-maven-plugin diff --git a/asf-site-src/source/documentation/in-progress/releasedocmaker.md b/asf-site-src/source/documentation/in-progress/releasedocmaker.md index 6f86848..0a26337 100644 --- a/asf-site-src/source/documentation/in-progress/releasedocmaker.md +++ b/asf-site-src/source/documentation/in-progress/releasedocmaker.md @@ -46,9 +46,9 @@ In order to solve these problems, releasedocmaker was written to automatically g # Requirements -* Python 2.6 with dateutil extension +* Python 2.7 with dateutil extension -dateutil may be installed via pip: `pip install python-dateutil` +dateutil may be installed via pip: `pip2 install python-dateutil` # Basic Usage diff --git a/asf-site-src/source/documentation/in-progress/shelldocs.md b/asf-site-src/source/documentation/in-progress/shelldocs.md new file mode 100644 index 0000000..6627bc5 --- /dev/null +++ b/asf-site-src/source/documentation/in-progress/shelldocs.md @@ -0,0 +1,141 @@ +<!--- + 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. +--> + +shelldocs +=============== + + +<!-- MarkdownTOC levels="1,2" autolink="true" --> + +* [Purpose](#purpose) +* [Requirements](#requirements) +* [Function Annotations](#function-annotations) + * [Audience / Stability](#audience--stability) + * [Multiple Parameters](#multiple-parameters) + * [Return Values](#return-values) + * [Code Example](#code-example) +* [Basic Usage](#basic-usage) +* [Skipping Files](#skipping-files) +* [Avoiding Private or Non-Replaceable Functions](#avoiding-private-or-non-replaceable-functions) +* [Lint Mode](#lint-mode) + +<!-- /MarkdownTOC --> + + +# Purpose + +Some projects have complex shell functions that act as APIs. `shelldocs` provides an annotation system similar to JavaDoc. It allows a developer to autogenerate MultiMarkdown documentation files as input to other processing systems. + +# Requirements + +* Python 2.7 + +# Function Annotations + +`shelldocs` works by doing simple parsing of shell scripts. As such, it looks for code that matches this pattern: + +```bash +## @annotation +function functioname() { + ... +} +``` + +This is Korn shell syntax that other shell languages (such as bash) will correctly interpret as a function. + +Note that the comment has two hash ('#') marks. The content of the comment is key. This is what `shelldocs` will turn into documentation. The following annotations are supported: + +| Annotation | Required | Description | Acceptable Values | Default | +|:---- |:---- |:--- |:--- |:-- | +| @description | No | What this function does, intended purpose, etc. | text | None | +| @audience | Yes | Who should use this function? | public, private,| None | +| @stability | Yes | Is this function going to change? | stable, evolving | None | +| @replaceable | No | Is this function safely 'monkeypatched'? | yes or no | No | +| @param | No | A single parameter| A single keyword. e.g., 'seconds' to specify that this function requires a time in seconds | None | +| @return | No | What does this function return? | text | Nothing | + +## Audience / Stability + +This values are the shell equivalents to the Java versions present in Apache Yetus Audience Annotations. + +## Multiple Parameters + +Each parameter requires it's own `@param` line and they must be listed in order. + +## Return Values + +It is recommended that multiple `@return` entries should be used when multiple values are possible. For example: + +```bash +## @return 0 - success +## @return 1 - failure +``` + +## Code Example + +```bash +## @description This is an example +## @description of what one can do. +## @audience public +## @stability stable +## @param integer +## @param integer +## @return sum +function add_two_numbers() { + return (($1 + $2)) +} +``` + +# Basic Usage + +The `shelldocs` executable requires at least one input file and either an output file or to run in lint mode. Lint mode is covered below. + +```bash +$ shelldocs --output functions.md --input myshelldirectory +``` + +This will process all of the files in `myshelldirectory` that end in `sh` and generate an output file called `functions.md`. This file will contain a table of contents of all of the functions arranged by audience, stability, and replace-ability. + +# Skipping Files + +When processing directories, it may be desirable to avoid certain files. This may be done by including a comment in the file: + +```bash +# SHELLDOC-IGNORE +``` + +This comment tells `shelldocs` that this file should not be processed. + +# Avoiding Private or Non-Replaceable Functions + +Some functions are not meant to be used by 3rd parties or cannot be easily replaced. These functions may be omitted from the documentation by using the `--skipprnorep` flag: + +```bash +$ shelldocs --skipprnorep --input directory --output file.md +``` + +# Lint Mode + +In order to ensure minimal documentation, `shelldocs` has a `--lint` mode that will point out functions that are missing required annotations: + +```bash +$ shelldocs --input directory --lint +``` + +This will process `directory` and inform the user of any such problems. diff --git a/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.md b/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.md index d8cc191..58b6920 100644 --- a/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.md +++ b/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.md @@ -20,12 +20,17 @@ Yetus Maven Plug-in =================== +<!-- MarkdownTOC levels="1,2" autolink="true" --> + * [Introduction](#introduction) * [File Utility Goals](#file-utility-goals) * [bin4libs](#bin4libs) * [symlink](#symlink) * [parallel-mkdirs](#parallel-mkdirs) * [releasedocmaker](#releasedocmaker) +* [shelldocs](#shelldocs) + +<!-- /MarkdownTOC --> # Introduction @@ -160,7 +165,7 @@ This goal runs releasedocmaker without the need to download or build an Apache Y <id>rdm</id> <phase>pre-site</phase> <goals> - <goal>releaseodcmaker</goal> + <goal>releasedocmaker</goal> </goals> <configuration> <projects> @@ -195,3 +200,31 @@ The configuration options generally map 1:1 to the `releasedocmaker` executable' | `sorttype` | --sorttype | resolutiondate | | `useToday` | --usetoday | false | | `versions` | ArrayList; --versions | `${project.version}` | + +# shelldocs + +Similar to the `releasedocmaker` goal, the `shelldocs` goal runs the Apache Yetus `shelldocs` utility against a given set of input files or directories and generates a single output MultiMarkdown file: + + <plugin> + <groupId>org.apache.yetus</groupId> + <artifactId>yetus-maven-plugin</artifactId> + <executions> + <execution> + <id>shelldocs</id> + <phase>pre-site</phase> + <goals> + <goal>shelldocs</goal> + </goals> + </execution> + </plugin> + + + +The configuration options generally map 1:1 to the `shelldocs` executable's options. Unless otherwise specified, defaults are set by the actual executable. + +| Option | Description | Default | +|--------|-------------|---------| +| `lint` | boolean; --lint | false | +| `output` | --output | `${project.build.directory}/generated-site/markdown/${project.name}.md` | +| `inputs` | ArrayList; --input ... | *sh files located in`${project.basedir}/src/main/shell` | +| `skipprnorep` | --skipprnorep | false |