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 <[email protected]>
AuthorDate: Fri Apr 5 09:52:33 2019 -0700
YETUS-431. shelldocs is undocumented
Signed-off-by: Allen Wittenauer <[email protected]>
---
.../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 |
