Redirect GeoAPI pending javadoc to GeoAPI snapshot.

Update build instruction about the need to remove underscore in directories generated by Sphinx.
opengeospatial · Sep 18, 2019 · d1efe8b · d1efe8b
1 parent 54a640a
commit d1efe8b
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -6,18 +6,29 @@ The pages are generated by the commands shown below.
 
 ## Prerequites
 
+* Git
 * Java 11 or above
 * [Maven 3](http://maven.apache.org/)
 * [Python 3](https://www.python.org/)
 * [Sphinx](http://www.sphinx-doc.org/) for Python 3
-* A checkout of this branch
-* A checkout of `3.1.x` branch
-* A checkout of `master` branch
+
+
+### Checkout branches
+
+Following commands need to be executed only once
+(directory names and locations can be different if desired):
+
+```
+git clone https://github.com/opengeospatial/geoapi master
+cd master
+git worktree add ../3.1.x 3.1.x
+git worktree add ../site gh-pages
+```
 
 
 ## Generating the web site
 
-Execute the following command in the directory containing this branch:
+Execute the following command in the directory containing this `gh-pages` branch:
 
 ```
 export GEOAPI_SITE=`pwd`
@@ -36,15 +47,22 @@ Execute the following commands in the directory containing the GeoAPI master bra
 sphinx-build-3 -b html src/site/sphinx $GEOAPI_SITE/snapshot/python
 ```
 
-Then:
+
+### Manual modifications
+
+Move Javadoc to `snapshot` directory for making clear that they are not yet approved.
+In addition of following commands, search and replace all occurrences of `apidocs` by
+`../snapshot/javadoc` in URLs of the `geoapi` subdirectory.
 
 ```
 cd $GEOAPI_SITE
 mv geoapi/apidocs/* snapshot/javadoc/
 rmdir geoapi/apidocs
 ```
 
-In the `geoapi` subdirectory, replace all occurrences of `apidocs` by `../snapshot/javadoc` in URLs.
+In Python documentation, remove the underscore in `_static` and `_images` directory names.
+This will again require manual replacements of those words in the URL of all HTML pages.
+
 Finally verify if there is some old files that should be removed.
 The following example list files older than 10 days.
 Be careful to not delete files that are not generated by above Maven commands,

diff --git a/geoapi-pending/apidocs/index.html b/geoapi-pending/apidocs/index.html
@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>GeoAPI pending javadoc</title>
+    <meta charset="UTF-8">
+  </head>
+  <body>
+    <h1>GeoAPI pending javadoc</h1>
+    <p>
+      "GeoAPI pending" is a module containing experimental interfaces not yet ready for inclusion in a GeoAPI release.
+      For the javadoc of interfaces targeted for next release, see <a href="../../snapshot/javadoc/index.html">GeoAPI snapshot</a>.
+      For the pending interfaces not included in above-cited javadoc, see the
+      <a href="https://github.com/opengeospatial/geoapi/tree/master/geoapi-pending/src/main/java/org/opengis">GitHub repository</a>.
+    </p>
+  </body>
+</html>