Update the links to documentation in the sofware development pages (g…

…eonetwork#7408) * Update the links to documentation to https://docs.geonetwork-opensource.org/ in the sofware development pages * Updating software developer, CONTRIBUTING.md, and wiki to reflect mkdocs change I found that the CONTRIBUTING.md requested developer docuemntation (on new libraries and dependencies) but did not indicate *where* to add such information. I assumed adding it ot the README.md files is the correct choice. I also updated the wiki pages referenced by this content: - https://github.com/geonetwork/core-geonetwork/wiki/Git-merge-branching-good-practices - https://github.com/geonetwork/core-geonetwork/wiki/How-to-contribute * Update software_development/README.md Co-authored-by: Jody Garnett <[email protected]> --------- Co-authored-by: Jody Garnett <[email protected]>
GeoCat · Oct 10, 2023 · b8c8a3f · b8c8a3f
1 parent 6ee146a
commit b8c8a3f
Show file tree

Hide file tree

Showing 15 changed files with 216 additions and 39 deletions.
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -0,0 +1,4 @@
+# These are supported funding model platforms
+
+github: [osgeo]
+cusotm: ['https://github.com/geonetwork/core-geonetwork/wiki#financial-support','https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=LDTWEL3XKUVU8&source=url','https://www.osgeo.org/about/how-to-become-a-sponsor/']
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,20 @@
+
+<!--Include a few sentences describing the overall goals for this Pull Request-->
+
+<!-- Please help our volunteers reviewing this PR by completing the following items. 
+Ask in a comment if you have troubles with any of them. -->
+
+# Checklist
+
+- [ ] I have read the [contribution guidelines](https://github.com/geonetwork/core-geonetwork/blob/main/CONTRIBUTING.md
+- [ ] *Pull request* provided for `main` branch, backports managed with label
+- [ ] *Good housekeeping* of code, cleaning up comments, tests, and documentation
+- [ ] *Clean commit history* broken into understandable chucks, avoiding big commits with hundreds of files, cautious of reformatting and whitespace changes
+- [ ] *Clean commit message*s, longer verbose messages are encouraged
+- [ ] *API Changes* are identified in commit messages
+- [ ] *Testing* provided for features or enhancements using [automatic tests](https://github.com/geonetwork/core-geonetwork/blob/main/software_development/TESTING.md))
+- [ ] *User documentation* provided for new features or enhancements in [mannual](https://github.com/geonetwork/core-geonetwork/tree/main/docs/manual)
+- [ ] *Build documentation* provided for development instructions in `README.md` files
+- [ ] *Library management* using `pom.xml` dependency management. Update build documentation with intended library use and library tutorials or documentation
+
+<!--Submitting the PR does not require you to check all items, but by the time it gets merged, they should be either satisfied or not applicable.-->
diff --git a/.gitignore b/.gitignore
@@ -13,6 +13,7 @@ git*.properties
 */*/target/
 */target/
 .*/
+!.github
 #GeoNetwork*
 /geonetwork*
 camel-harvesters/wfsfeature-harvester/logs

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,6 +35,6 @@ Thank you for contributing to GeoNetwork:
 
 * Build documentation: All build and development instructions managed in repository `README.md` files.
 
-* New libraries: Do not commit jars, use maven `pom.xml` to declare dependencies where needed, and `src/pom.xml` dependency management to manage version numbers. Document what the library does in GeoNetwork, how it interacts or extends GeoNetwork, with references to official library tutorials or documentation.
+* New libraries: Do not commit jars, use maven `pom.xml` to declare dependencies where needed, and `src/pom.xml` dependency management to manage version numbers. Use build documentation to share what the library does in GeoNetwork, how it interacts or extends GeoNetwork, with references to official library tutorials or documentation.
 
 For more information see [How to contribute](https://github.com/geonetwork/core-geonetwork/wiki/How-to-contribute) (wiki).
diff --git a/README.md b/README.md
@@ -1,10 +1,10 @@
 # GeoNetwork Open-source
 
-# Build Health
+## Build Health
 
 [![Build Status](https://github.com/geonetwork/core-geonetwork/actions/workflows/linux.yml/badge.svg?branch=main)](https://github.com/geonetwork/core-geonetwork/actions/workflows/linux.yml?query=branch%3Amain)
 
-# Features
+## Features
 
 * Immediate search access to local and distributed geospatial catalogues
 * Uploading and downloading of data, graphics, documents, pdf files and any other content type
@@ -15,15 +15,18 @@
 * Fine-grained access control with group and user management
 * Multi-lingual user interface
 
-# Documentation
+## Documentation
 
-User documentation is managed in the [geonetwork/doc](https://github.com/geonetwork/doc) repository covering all releases of GeoNetwork.
+The Geonetwork Manual and Online Help are included in the `docs/manual` folder. This content is compiled into html pages during a release for a publishing on docs.geonetwork-opensource.org website.
 
-The `docs` folder includes [geonetwork/doc](https://github.com/geonetwork/doc) as a git submodule. This documentation is compiled into html pages during a release for publishing on the [geonetwork-opensource.org](http://geonetwork-opensource.org) website.
+* [docs.geonetwork-opensource.org](https://docs.geonetwork-opensource.org)
 
-Developer documentation located in README.md files in the code-base:
+The online help is compiled into html pages during a release and is included in the `war` web archive.
 
-* General documentation for the project as a whole is in this README.md
-* [Software Development Documentation](/software_development/) provides instructions for setting up a development environment, building Geonetwork, compiling user documentation, and making a releases
-* Module specific documentation can be found in each module (assuming there is module specific documentation required)
+## Developer Documentation
 
+Developer documentation located in ``README.md`` files in the code-base:
+
+* General documentation for the project as a whole is in this [README.md](README.md)
+* [Software Development Documentation](/software_development/) provides instructions for setting up a development environment, building Geonetwork, compiling user documentation, and making a releases.
+* Module specific documentation can be found in each module:
diff --git a/datastorages/README.md b/datastorages/README.md
@@ -0,0 +1,12 @@
+# Data storage
+
+Extensions for data storage (used for storage resources such as record attachments and thumbnails).
+
+Core provides the default implementation for a data directory:
+
+* org.fao.geonet.resource.FileResources
+
+For more information see:
+
+* org.fao.geonet.resource.Resources
+
diff --git a/datastorages/cmis/README.md b/datastorages/cmis/README.md
@@ -0,0 +1,11 @@
+# CMIS Data storage
+
+Extension for data storage (used for storage resources such as record attachments and thumbnails).
+
+* cmis: content management interoperability services
+
+This data storage is based on the Apache Chemistry project which has been retired.
+
+Reference:
+
+* https://chemistry.apache.org/java/opencmis.html
diff --git a/datastorages/jcloud/README.md b/datastorages/jcloud/README.md
@@ -0,0 +1,10 @@
+# JCloud Data storage
+
+Extension for data storage (used for storage resources such as record attachments and thumbnails).
+
+This extension uses the Apache JCloud library for portable storage across different cloud providers.
+
+Reference:
+
+* https://jclouds.apache.org
+
diff --git a/datastorages/s3/README.md b/datastorages/s3/README.md
@@ -0,0 +1,9 @@
+# S3 Data storage
+
+Extension for data storage (used for storage resources such as record attachments and thumbnails).
+
+This extension uses Amazon Web Services Simple Storage Service (S3) data storage directly.
+
+Reference:
+
+* https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
diff --git a/docs/manual/docs/install-guide/installing-from-source-code.md b/docs/manual/docs/install-guide/installing-from-source-code.md
@@ -20,8 +20,8 @@ If you need a more powerful container, we recommend [Apache Tomcat](http://tomca
 
 We recommend the following stable releases of Tomcat:
 
--   Apache Tomcat 8.5
 -   Apache Tomcat 9.0
+-   Apache Tomcat 8.5
 
 ### Database
 
@@ -159,18 +159,18 @@ Please refer to the [Maven documentation](http://www.sonatype.com/books/mvnref-b
 
 ### Run embedded Jetty server
 
-Maven comes with built-in support for Jetty via a [plug-in](http://docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin).
+Maven comes with built-in support for Jetty via a [plug-in](https://eclipse.dev/jetty/documentation/jetty-9/index.html#maven-and-jetty).
 
 To run GeoNetwork with the embedded Jetty server you have to change directory to the root of the **web** module, and then execute the following Maven command:
 
 ``` shell
 mvn jetty:run -Penv-dev
 ```
 
-After a while, GeoNetwork should be accessible at: <http://localhost:8080/geonetwork>
+After some moments of startup and initialization, GeoNetwork is available at: <http://localhost:8080/geonetwork>
 
-For changes related to the user interface in the ``web-ui`` module or the metadata schemas in the `as` module, these can be deployed in Jetty executing the following Maven command in the **web** module:
+For changes related to the user interface in the ``web-ui`` module or the metadata schemas in the `schemeas` module, these can be deployed in Jetty executing the following Maven command in the **web** module:
 
 ``` shell
-mvn process-resources
+mvn process-resources -DschemasCopy=true
 ```
diff --git a/software_development/BUILDING.md b/software_development/BUILDING.md
@@ -1,6 +1,6 @@
 # Building
 
-See [Installing from source code](https://geonetwork-opensource.org/manuals/4.0.x/en/install-guide/installing-from-source-code.html) (Installation Guide)
+See [Installing from source code](https://docs.geonetwork-opensource.org/latest/install-guide/installing-from-source-code/) (Installation Guide)
 
 Build GeoNetwork
 ----------------
@@ -102,7 +102,6 @@ GeoNetwork requires an Elasticsearch instance as an index.
 
 3. For alternatives see [es/readme](../es/README.md).
 
-
 Run Kibana
 ----------
 

diff --git a/software_development/GITHUB.md b/software_development/GITHUB.md
@@ -33,4 +33,4 @@ To checkout a branch from upstream::
 GeoNetwork uses feature branches for development, and a pull-request workflow for review:
 
 * [Contributing](../CONTRIBUTING.md).
-* [Making a pull request](https://geonetwork-opensource.org/manuals/trunk/en/contributing/making-a-pull-request.html).
+* [Making a pull request](https://docs.geonetwork-opensource.org/latest/contributing/making-a-pull-request/).
diff --git a/software_development/OVERVIEW.md b/software_development/OVERVIEW.md
@@ -1,4 +1,4 @@
-# GeoNetwork Architecture Overview
+# GeoNetwork Overview
 
 GeoNetwork is a modular application, managed using the spring framework, divided into clear application tiers.
 
@@ -9,19 +9,73 @@ GeoNetwork uses a wide range of technologies:
 * [Angular](https://angular.io/) web framwork providing model-view-controller architecture with data model binding
 * [Apache Lucene](https://lucene.apache.org) text index to facilitate searching
 * [Bootstrap](https://getbootstrap.com/) front-end open source toolkit providing response page layout
-* [Elasticsearch](https://www.elastic.co/elasticsearch/) to manage usage statistics and reporting
+* [Elasticsearch](https://www.elastic.co/elasticsearch/) full-text search
 * [GeoTools](https://geotools.org/) Java GIS toolkit used to provide a spatial index
 * [OpenLayers](http://openlayers.org) web mapping framework
 * [Saxon](http://www.saxonica.com/) XSLT engine used extensively to process XML documents
 * [Spring framework](https://spring.io/) Java web application framework used to "wire" components together
 
-GeoNetwork is Java Web Application, requiring an application server to operate:
-
-* [Jetty](https://www.eclipse.org/jetty/) application server for standaline distribution
-* [Apache Tomcat](http://tomcat.apache.org/) application server for WAR distribution
-
 GeoNetwork configuration is managed via:
 
 * Configuration is managed via [Hibernate Object/Relational Mapping](https://hibernate.org/orm/) with [H2 Database Engine](https://www.h2database.com/) default for local testing, [PostgreSQL](https://www.postgresql.org/) recommended for production. Additional dialects are available for environments restricted to Oracle or SQLServer.
 
 * Data Directory for the management of thumbnails, attachments and other application files
+
+## Architecture
+
+GeoNetwork is a modular web application, managed using the spring framework, divided into clear application tiers.
+
+![GeoNetwork Architecture](geonetwork-architecture.png "GeoNetwork Architecture")
+
+The application is built on top of:
+
+* Elasticsearch: full-text search
+* Database: record persistance
+* Data directory: attachments and application files
+
+## Technologies
+
+## Hibernate Object/Relational Mappping
+
+
+
+Geonetwork Reference:
+
+* [domain](../domain/README.md)
+
+Reference:
+
+* https://hibernate.org/orm/
+
+### Java Enterprise Edition
+
+GeoNetwork is a Java "web application", following Java Enterprise Edition standard (establishing Servlet and related interfaces, and the web-application-archive bundle).
+
+Note: Java Enterprise Edition is in the process of renaming to Jakarata Enterprise Edition
+
+The ``geonetwork.war`` requires an application server to operate:
+
+* [Jetty](https://www.eclipse.org/jetty/) application server for standaline distribution.
+
+  Jetty 9 is the last JavaEE compatible release.
+
+* [Apache Tomcat](http://tomcat.apache.org/) application server for WAR distribution
+
+  Apache Tomcat 9.x is the last JavaEE compatible release.
+
+Reference:
+
+* https://javaee.github.io (Legacy Java EE Home)
+
+## Libraries
+
+### mapfish-print-v2
+
+The mapfish-print-v2 library is used for PDF generation, using a combinatino of GeoTools and OpenPDF library.
+
+The library is used for thumbnail generation.
+
+Reference:
+
+* http://github.com/mapfish/mapfish-print-v2
+* https://github.com/LibrePDF/OpenPDF
diff --git a/software_development/README.md b/software_development/README.md
@@ -1,8 +1,8 @@
 # Software Development
 
-This manual is for software developers customizing or developing GeoNetwork:
+This manual is for developers customizing or developing GeoNetwork:
 
-* [GeoNetwork Architecture Overview](OVERVIEW.md) describing technologies used and application components.
+* [Overview](OVERVIEW.md) describing architecture, technologies, and libraries used.
 * Development environment:
 
   * [Tools](TOOLS.md)  
@@ -13,15 +13,15 @@ This manual is for software developers customizing or developing GeoNetwork:
   * [Eclipse IDE](ECLIPSE.md)
   * [IntelliJ IDE](INTELLIJ.md).
 
-  See [Installing from source code](https://geonetwork-opensource.org/manuals/4.0.x/en/install-guide/installing-from-source-code.html) (Installation Guide)
-
-* Writing documentation: see [Writing documentation](https://geonetwork-opensource.org/manuals/trunk/en/contributing/writing-documentation.html) (Contributing Guide).
-* Release process: See [Doing a release](https://geonetwork-opensource.org/manuals/trunk/en/contributing/doing-a-release.html) (Contributing Guide).
+  See [Installing from source code](https://docs.geonetwork-opensource.org/latest/install-guide/installing-from-source-code/) (Installation Guide)
 
+* Writing documentation: see [Documentation Guide](https://docs.geonetwork-opensource.org/latest/devel/docs/) (Contributing Guide).
+* Writing documentation: see [Documentation Guide](https://docs.geonetwork-opensource.org/latest/devel/docs/) (Contributing Guide).
+* Release process: See [Doing a release](https://docs.geonetwork-opensource.org/latest/contributing/doing-a-release/) (Contributing Guide).
 
 If you just want to use the software and are looking for instructions on how to do that,
 there is a lot of documentation for users,  administrators, metadata editors and application
-maintainers at: [GeoNetwork Documentation](http://geonetwork-opensource.org/manuals/trunk/eng/users/index.html).
+maintainers at: [GeoNetwork Documentation](https://docs.geonetwork-opensource.org/latest/).
 
 # Quickstart
 
@@ -48,3 +48,4 @@ Get GeoNetwork running - the short path:
    ```
 
 4. The application is opened on http://localhost:8080/geonetwork 
+
diff --git a/software_development/TOOLS.md b/software_development/TOOLS.md
@@ -19,24 +19,77 @@ Our source code is maintained on GitHub:
 
   * [iso19115-3.2018](https://github.com/metadata101/iso19115-3.2018)
 
-## Java 8
+## Java 11
 
-GeoNetwork requires a Java 8 development environment:
+GeoNetwork requires a Java 11 development environment:
 
-* Recommend using the Java 8 distribution available from your operating system
-* [Adoptium OpenJDK8 (LTS)](https://adoptium.net/temurin/archive/?version=8) for windows or macOS installers
+* Recommend using the Java 11 distribution available from your operating system
+* [Adoptium OpenJDK8 (LTS)](https://adoptium.net/temurin/archive/?version=11) for windows or macOS installers
 
-We do not support development on Java 11 at this time.
+We no longer support Java 8 at this time.
+
+## Elasticsearch
+
+GeoNetwork uses Elasticsearch as a full-text search engine.
+
+```
+cd es
+docker-compose up
+```
+
+* Elasticsearch: http://localhost:9200
+* Kibana: http://localhost:5601
+
+GeoNetwork Reference:
+
+* [es/readme](../es/README.md)
+
+Reference:
+
+* https://www.elastic.co/guide/index.html
 
 ## Apache Maven
 
 We make use of the Apache Maven [Apache Maven](https://maven.apache.org/) build system.
 
+To build and run:
+```
+mvn clean install -DskipTests
+cd web
+mvn jetty:run
+```
+
+* GeoNetwork: http://localhost:8080/geonetwork
+
 Maven repository is available at repo.osgeo.org:
 
 * https://repo.osgeo.org/repository/release/
 * https://repo.osgeo.org/repository/snapshot/
 
-## Sphinx 
+GeoNetwork Reference
+
+* [software_development/building](BUIDLING.md)
+* [web](../web/README.md)
+
+Reference:
+
+* https://maven.apache.org/index.html
+
+## Material for MkDocs
+
+Documentation is built using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme, built using python ***mkdocs*** generator.
+
+```
+cd docs/mannual
+pip3 install -r requirements.txt
+mkdocs serve
+```
+
+GeoNetwork Reference:
+
+* [docs/manual](../docs/manual/README.md)
+
+Reference:
 
-Documentation is built using [Sphinx](https://www.sphinx-doc.org/) python documentation generator.
+* https://squidfunk.github.io/mkdocs-material/
+* https://www.mkdocs.org