yetus-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a.@apache.org
Subject [yetus] branch master updated: YETUS-431. shelldocs is undocumented
Date Mon, 08 Apr 2019 23:00:07 GMT
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 <aw@apache.org>
AuthorDate: Fri Apr 5 09:52:33 2019 -0700

    YETUS-431. shelldocs is undocumented
    
    Signed-off-by: Allen Wittenauer <aw@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 |


Mime
View raw message