You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jdo-dev@db.apache.org by GitBox <gi...@apache.org> on 2021/04/04 12:15:23 UTC
[GitHub] [db-jdo-site] tobous commented on a change in pull request #14: Update README.md
tobous commented on a change in pull request #14:
URL: https://github.com/apache/db-jdo-site/pull/14#discussion_r606792654
##########
File path: README.md
##########
@@ -7,18 +7,21 @@ The website is mirrored on https://apache.github.io/db-jdo-site/.
## Building the Site
-The content and styling of the site is defined in the [AsciiDoc](https://asciidoc.org/) format. It is built using [Maven](https://maven.apache.org/).
+The content and styling of the site is defined in the [AsciiDoc](https://asciidoc.org/) format. It is built using [Maven](https://maven.apache.org/). For details on publishing the site see section [Publishing the Site](#publishing-the-site).
The site can be built by calling `mvn clean compile`. This generates the HTML files in `target/site`.
+Most of the site will work with the exception of the javadoc file downloads.
+If needed, call `mvn package`. This copies the javadoc files to `target/site`.
+The site can then be viewed by opening the local file `target/site/index.html` in a browser.
### Adding Javadoc
The site contains a packaged version of the JDO API javadoc. It can be updated as follows:
* Create the javadoc jar (e.g. jdo-api-3.2-javadoc.jar) in the db-jdo repository by calling `mvn clean install -Papache-release` in the api submodule.
-* Create a new folder under docs e.g. docs/api32.
-* Copy the javadocs jar info the new folder: e.g. `cp jdo-api-3.2-javadoc.jar docs/api32`.
-* Create a new subfolder docs/api32/jdo-api-3.2-javadoc
+* Create a new folder under docs e.g. `src/main/resources/javadoc/api32`.
Review comment:
```suggestion
* Create a new folder under in the javadoc resources directory, e.g. `src/main/resources/javadoc/api32`.
```
##########
File path: README.md
##########
@@ -32,15 +35,27 @@ This repository contains the JDO website source.
* The AsciiDoc sources can be found in `src/main/asciidoc`.
* The website menu is defined in `src/main/template`.
- * The converter for migrating the old HTML files to AsciiDoc can be found in `src/main/java`
+ * The converter for migrating the old HTML files to AsciiDoc can be found in `src/main/java`.
+ * Additional pre-compiled resources are located in `src/main/resources`.
-Contributions to this repository follow the default [GitHub workflow](https://guides.github.com/introduction/flow/) using [forks](https://guides.github.com/activities/forking/).
+Contributions to this repository follow the default [GitHub workflow](https://guides.github.com/introduction/flow/)
+using [forks](https://guides.github.com/activities/forking/).
To contribute changes, you can follow these steps:
* Adapt the AsciiDoc files in `src/main/asciidoc` or the website menu in `src/main/template`.
- * Call `mvn clean compile` to build the site and verify the generated website by viewing it locally with a web browser.
- * Commit the source changes (not the build artifacts) and open a pull request.
+ * Build the site (see [above](#building-the-site) and verify the generated website by viewing `target/site/index.html` locally with a web browser.
Review comment:
```suggestion
* Build the site (see [above](#building-the-site)) and verify the generated website by viewing `target/site/index.html` locally with a web browser.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Fwd: [GitHub] [db-jdo-site] tobous commented on a change in pull
request #14: Update README.md
Posted by Craig Russell <ap...@gmail.com>.
Hi Tobous,
Thanks for your careful review and for these updates.
I think we're now done with the README, modulo finding all of the missing full stops and until we change the name of the master branch...
Craig
> Begin forwarded message:
>
> From: GitBox <gi...@apache.org>
> Subject: [GitHub] [db-jdo-site] tobous commented on a change in pull request #14: Update README.md
> Date: April 4, 2021 at 5:15:23 AM PDT
> To: jdo-dev@db.apache.org
> Reply-To: jdo-dev@db.apache.org
>
>
> tobous commented on a change in pull request #14:
> URL: https://github.com/apache/db-jdo-site/pull/14#discussion_r606792654
>
>
>
> ##########
> File path: README.md
> ##########
> @@ -7,18 +7,21 @@ The website is mirrored on https://apache.github.io/db-jdo-site/.
>
> ## Building the Site
>
> -The content and styling of the site is defined in the [AsciiDoc](https://asciidoc.org/) format. It is built using [Maven](https://maven.apache.org/).
> +The content and styling of the site is defined in the [AsciiDoc](https://asciidoc.org/) format. It is built using [Maven](https://maven.apache.org/). For details on publishing the site see section [Publishing the Site](#publishing-the-site).
>
> The site can be built by calling `mvn clean compile`. This generates the HTML files in `target/site`.
> +Most of the site will work with the exception of the javadoc file downloads.
> +If needed, call `mvn package`. This copies the javadoc files to `target/site`.
> +The site can then be viewed by opening the local file `target/site/index.html` in a browser.
>
> ### Adding Javadoc
>
> The site contains a packaged version of the JDO API javadoc. It can be updated as follows:
>
> * Create the javadoc jar (e.g. jdo-api-3.2-javadoc.jar) in the db-jdo repository by calling `mvn clean install -Papache-release` in the api submodule.
> -* Create a new folder under docs e.g. docs/api32.
> -* Copy the javadocs jar info the new folder: e.g. `cp jdo-api-3.2-javadoc.jar docs/api32`.
> -* Create a new subfolder docs/api32/jdo-api-3.2-javadoc
> +* Create a new folder under docs e.g. `src/main/resources/javadoc/api32`.
>
> Review comment:
> ```suggestion
> * Create a new folder under in the javadoc resources directory, e.g. `src/main/resources/javadoc/api32`.
> ```
>
> ##########
> File path: README.md
> ##########
> @@ -32,15 +35,27 @@ This repository contains the JDO website source.
>
> * The AsciiDoc sources can be found in `src/main/asciidoc`.
> * The website menu is defined in `src/main/template`.
> - * The converter for migrating the old HTML files to AsciiDoc can be found in `src/main/java`
> + * The converter for migrating the old HTML files to AsciiDoc can be found in `src/main/java`.
> + * Additional pre-compiled resources are located in `src/main/resources`.
>
> -Contributions to this repository follow the default [GitHub workflow](https://guides.github.com/introduction/flow/) using [forks](https://guides.github.com/activities/forking/).
> +Contributions to this repository follow the default [GitHub workflow](https://guides.github.com/introduction/flow/)
> +using [forks](https://guides.github.com/activities/forking/).
>
> To contribute changes, you can follow these steps:
>
> * Adapt the AsciiDoc files in `src/main/asciidoc` or the website menu in `src/main/template`.
> - * Call `mvn clean compile` to build the site and verify the generated website by viewing it locally with a web browser.
> - * Commit the source changes (not the build artifacts) and open a pull request.
> + * Build the site (see [above](#building-the-site) and verify the generated website by viewing `target/site/index.html` locally with a web browser.
>
> Review comment:
> ```suggestion
> * Build the site (see [above](#building-the-site)) and verify the generated website by viewing `target/site/index.html` locally with a web browser.
> ```
>
>
>
>
> --
> This is an automated message from the Apache Git Service.
> To respond to the message, please log on to GitHub and use the
> URL above to go to the specific comment.
>
> For queries about this service, please contact Infrastructure at:
> users@infra.apache.org
>
>
Craig L Russell
clr@apache.org