Adding asciidoc and new site publish documentation
diff --git a/.gitignore b/.gitignore
index b272865..48b1d6c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@
*.iml
.idea/
site-content/
+.site-content/
diff --git a/pom.xml b/pom.xml
index 6e606e5..2b67f7d 100644
--- a/pom.xml
+++ b/pom.xml
@@ -51,7 +51,7 @@
<siteRepositoryUrl>scm:git:https://gitbox.apache.org/repos/asf/archiva-web-content.git</siteRepositoryUrl>
- <scmPubCheckoutDirectory>site-content</scmPubCheckoutDirectory>
+ <scmPubCheckoutDirectory>.site-content</scmPubCheckoutDirectory>
<scmPublishBranch>asf-staging</scmPublishBranch>
<scmPublishPath>/</scmPublishPath>
@@ -80,9 +80,29 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
+ <version>3.7.1</version>
<configuration>
<skipDeploy>true</skipDeploy>
- </configuration>
+ <asciidoc>
+ <!-- optional site-wide AsciiDoc attributes -->
+ <attributes>
+ <icons>font</icons>
+ <source-highlighter>coderay</source-highlighter>
+ <coderay-css>style</coderay-css>
+ <toclevels>2</toclevels>
+ </attributes>
+ <templateDirs>
+ <dir>src/site/slim-templates</dir>
+ </templateDirs>
+ </asciidoc>
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <version>${asciidoctor.maven.plugin.version}</version>
+ </dependency>
+ </dependencies>
<executions>
<execution>
<id>stage-for-scm-publish</id>
diff --git a/src/site/apt/developers/publishing-site.apt b/src/site/apt/developers/publishing-site.apt
deleted file mode 100644
index b5438ad..0000000
--- a/src/site/apt/developers/publishing-site.apt
+++ /dev/null
@@ -1,159 +0,0 @@
- ------
- Archiva Sites Publishing
- ------
-
-Publishing the Archiva Site
-
- The Archiva site, documentation and reference documentation are now
- published to <<<http://archiva.apache.org/>>> using the
- {{{http://www.apache.org/dev/project-site.html#svnpubsub} ASF's svnpubsub}}
- service.
-
- The files published to the site are all stored under the Subversion
- repository at {{http://svn.apache.org/repos/asf/archiva/site-content/}}.
-
- This mostly operates like a normal site deployment, though there are some
- specific customisations and special instructions for the reference library.
- The processes follow those described for the
- {{{http://maven.apache.org/plugins/maven-scm-publish-plugin/}Maven SCM Publish Plugin}}
- for
- {{{http://maven.apache.org/plugins/maven-scm-publish-plugin/examples/one-module-configuration.html}
- Single module projects}} and
- {{{http://maven.apache.org/plugins/maven-scm-publish-plugin/examples/multi-module-configuration.html}
- Multi-module projects}} as applicable.
-
- Each site checks out the production site data into the <<<site-publish>>>
- directory of the current project, to avoid being cleaned as part of the
- build. It is ignored by <<<svn>>> operations, but you should ensure that
- the checkout is clean if you ever cancel or have a failure during a publish
- operation. You can check it is clean by ensuring there is no data from
- <<<git status>>> in that directory, or by removing it and having it get
- checked out again.
-
-* Editing and Publishing the Main Site
-
- The site displayed at the root of {{http://archiva.apache.org}} (where
- you are reading this) has its source code in Git at
- {{https://gitbox.apache.org/repos/asf/archiva-site.git}}.
-
- To edit and publish the site, do the following:
-
- [[1]] Checkout the source code from Git (if you follow the
- instructions in {{{./building.html} Building Archiva}}, you know
- how to have it.
-
- [[2]] Make edits and check them using <<<mvn site>>> or <<<mvn
- site:run>>> until satisfied.
-
- [[3]] Commit your changes (making sure your working copy is completely up
- to date first)
-
- [[4]] Publish the site:
-
-----
-mvn site-deploy
-----
-
- This site deployment can be done at any time, and is not tied to releases.
-
- Note that since the main site also contains the (large!) <<<docs>>> and
- <<<ref>>> directories in the <<<site-publish>>> directory, there is a
- special <<<setup-checkout>>> profile in place to get the initial checkout
- without those directories. This will normally be activated whenever the
- <<<site-publish>>> directory is missing - if you happen to have active
- profiles from your <<<settings.xml>>> you may need to enable it explicitly
- whenever you do a deployment and that checkout is missing: <<<mvn
- site-deploy -Psetup-checkout>>>
-
-* Editing and Publishing the Archiva Documentation
-
- The documentation displayed under the subdirectories of
- {{http://archiva.apache.org/docs/}} has its source code in Git at
- {{https://gitbox.apache.org/repos/asf/archiva.git}} directory archiva-docs, which
- is part of the main project checkout.
-
- The instructions for managing the documentation is the same as for the main
- site, being published from the directory using:
-
-----
-mvn site-deploy
-----
-
- However, in this case it is typically done as part of a release process -
- see {{{./releasing.html} Releasing Archiva}} for instructions on doing this.
-
- The documentation remains versioned based on the release it is related to.
- To best manage this with svnpubsub, the site is always published into a
- directory <<<docs/latest>>>, only requiring a small number of modifications
- to be made. Then, as part of the release instructions, the <<<latest>>>
- directory is copied to the versioned location - for example,
- <<<http://svn.apache.org/repos/asf/archiva/site-content/docs/1.4-M4>>>.
-
- For <<<site:stage>>> to apply correctly without needing a full checkout, a
- workaround is applied by setting the <<<distributionManagement/site/url>>>
- element to match that of the parent site. The value is then overridden with
- the correct value in the <<<maven-scm-publish-plugin>>> configuration. This
- avoids the Site plugin attempting to relativize links incorrectly.
-
-* Editing and Publishing the Reference Documentation
-
- The reference documentation, including JavaDocs and source cross-reference,
- is displayed under the URL {{http://archiva.apache.org/ref}}. At this
- time, only the latest reference documents are retained. They require quite
- a lot of space, and historical information is of less relevance to
- Archiva developers or users.
-
- To publish the latest reference documents, you need to run:
-
-----
-cd archiva-modules
-mvn site site:stage scm-publish:publish-scm
-or
-sh ./deploySite.sh
-----
-
- This will likely cause a very large commit, and should be done
- infrequently. Once per release is likely to be adequate.
-
-* Publishing Redback site
-
- The redback is stored under the Subversion repository at {{https://svn.apache.org/repos/asf/archiva/redback/redback-site/trunk}}.
-
- It's displayed under the URL {{http://archiva.apache.org/redback}}.
-
- To publish documentation, you need to run:
-
-----
-mvn site-deploy
-----
-
-* Publishing Redback Core reference
-
- The Redback core reference is displayed under the URL {{http://archiva.apache.org/redback/core}}.
-
- It contains javadoc for Redback core.
-
- To publish documentation, you need to run:
-
-----
-mvn clean site-deploy scm-publish:publish-scm
-or
-sh ./deploySite.sh
-----
-
-* Publishing Redback Components reference
-
- The Redback components reference is displayed under the URL {{http://archiva.apache.org/redback/components}}.
-
- It contains javadoc for Redback components.
-
- To publish documentation, you need to run:
-
-----
-mvn clean site-deploy scm-publish:publish-scm
-or
-sh ./deploySite.sh
-----
-
-
-
diff --git a/src/site/asciidoc/developers/publishing-site.adoc b/src/site/asciidoc/developers/publishing-site.adoc
new file mode 100644
index 0000000..25d12b2
--- /dev/null
+++ b/src/site/asciidoc/developers/publishing-site.adoc
@@ -0,0 +1,182 @@
+= Archiva Site Publishing
+Martin Stockhammer <martin_s@apache.org>
+2019-11-30
+:toc:
+
+== General information about the site publish process
+
+The archiva site is built from multiple different more or less independent modules. The build process
+uses `maven-site-plugin` for generating the static HTML pages and stylesheets and `scm-publish-plugin` for
+publishing the results to the repository.
+
+The generated HTML pages are stored at a git repository:
+https://gitbox.apache.org/repos/asf?p=archiva-web-content.git[`archiva-web-content.git`].
+
+The git repository contains a `.asf.yaml` file that defines the branch `asf-staging` as staging branch. The
+master branch is used by git-pub-sub to publish the official archiva site at https://archiva.apache.org .
+
+If you push something to the `asf-staging` branch you can see the changes immediately at https://archiva.staged.apache.org
+
+The maven site report and publishing plugins are configured to deploy the the asf-staging branch. That means the
+overall publishing process is the following:
+
+- Generate the site content for a module by using the scripts / maven
+- Use the maven publish plugin to push the generated pages to the asf-staging branch of archiva-web-content.git
+- Check the generated content at https://archiva.staged.apache.org/
+- If the result is fine, release the new content by merging the content from `asf-staging` to the `master` branch
+
+For all modules there exists a script that runs all the steps (apart from the check on the staged site). Currently
+the script runs only on Linux / Bash. For details see below.
+
+== Where is site content generated?
+
+The Archiva site is generated from the following components:
+
+[role="bodyTable"]
+|===
+|Component |Content |Git Repository |Path inside Repo |Publish Path |Skript
+
+|Archiva Site
+|Main Pages, like index.html. General information.
+|https://gitbox.apache.org/repos/asf?p=archiva-site.git[`archiva-site.git`]
+|/
+|/
+|`deploySite.sh`
+
+|Archiva Documentation
+|Archiva User Documentation. Archiva Configuration.
+|https://gitbox.apache.org/repos/asf?p=archiva.git[`archiva.git`]
+|/archiva-docs
+|/docs/${project.version}
+|`archiva-docs/deploySite.sh`
+
+|Archiva Reference Documentation
+|Developer documentation for Archiva, API Javadoc pages. Information for each maven module.
+|https://gitbox.apache.org/repos/asf?p=archiva.git[`archiva.git`]
+|/archiva-modules
+|/ref/${project.version}
+|`archiva-modules/deploySite.sh`
+
+|Redback Site
+|Pages for Redback. General information about redback.
+|https://gitbox.apache.org/repos/asf?p=archiva-redback-site.git[`archiva-redback-site.git`]
+|/
+|/redback
+|`deploySite.sh`
+
+|Redback Reference Documentation
+|Developer documentation for Redback, API Javadoc pages. Information for each maven module.
+|https://gitbox.apache.org/repos/asf?p=archiva-redback-core.git[`archiva-redback-core.git`]
+|/
+|/core/${project.version}
+|`deploySite.sh`
+
+|Archiva Component Documentation
+|Information about the Archiva Components
+|https://gitbox.apache.org/repos/asf?p=archiva-components.git[`archiva-components.git`]
+|/
+|/components
+|`deploySite.sh`
+
+|===
+
+
+== Tasks for publishing
+
+=== Using the script (Linux/Bash)
+
+The easiest way is always to use the script `deploySite.sh` in the directory of the corresponding repository.
+
+----
+cd <path inside repo for component>
+./deploySite.sh
+...
+...
+*****************************************
+>>>> Finished the site stage process <<<<
+> You can check the content in the folder target/staging or by opening the following url
+> file:///archiva/archiva-modules/target/staging/ref/3.0.0-SNAPSHOT/index.html
+>
+> If everything is fine enter yes. After that the publish process will be started.
+Do you want to publish (yes/no)? yes
+----
+
+When this output is shown you can check the staging output for this component only on the given path.
+
+If you enter `y` or `yes` here, the content will be pushed to the `asf-staging`-branch at `archiva-web-content.git`
+If you enter any other key, the process will be aborted.
+
+After the page was pushed to the `asf-staging`-branch, you can check the result at https://archiva.staged.apache.org/
+
+[NOTE]
+====
+If you would like to check the page with a local clone of archiva-web-content.git you can run the script with:
+
+ ./deploySite.sh -DsiteRepositoryUrl=scm:git:file:///${path-to-your-local-archiva}/archiva-web-content.git
+====
+
+
+If the result on the staged URL is fine you have to merge the branch to the master branch:
+
+----
+# git clone https://gitbox.apache.org/repos/asf/archiva-web-content.git
+cd archiva-web-content
+git checkout master
+git merge --ff-only asf-staging
+git push
+----
+
+=== Run the process manually
+==== Generating Site Pages for a component
+
+
+The script basically runs
+
+ mvn clean site
+ mvn site:stage
+
+The pom.xml has a plugin definition to checkout the repository as sparse checkout to a local directory `.site-content`
+The patterns for the sparse checkout are stored in the file `git-sparse-checkout-pattern`
+
+The content of the module and all submodules is put to the directory `target/staging/${Component Path}`
+
+
+==== Publishing to the staging branch
+
+This is the part that is run, when you answer `y` or `yes` for publishing.
+
+ mvn scm-publish:publish-scm
+
+This checks the differences in .site-content and pushes the differences to the `asf-staging` branch.
+
+
+== Information about Maven / Script configuration
+
+There are some properties in the pom.xml that are used by the deploySite.sh. You should always make sure, that
+these properties are set to the corresponding values for the given module:
+
+- <scmPubCheckoutDirectory>.site-content</scmPubCheckoutDirectory>: The directory for the sparse checkout
+- <scmPublishBranch>asf-staging</scmPublishBranch>: The staging branch
+- <scmPublishPath>/</scmPublishPath>: The path relative to the base URL where the content is placed
+
+The helper script `checkoutSite.sh` is used for running the sparse checkout of the content.
+
+For multi-module projects the CSS (site.css) is always relative to the module directory. Therefore, we have
+a link to the stylesheet at `/css/site.css` in `site.xml`
+
+
+== Information about site generation
+
+Most content is written in apt and xdoc. New documentation can/should be written in asciidoc. Asciidoc needs some css modification
+to get the styles right. So please check the generated content before publishing it.
+
+For multi-module builds you should add the central `/css/site.css` to the `<head>`-Section in `site.xml`. Because submodules
+include only their own site.css and not the parent stylesheets. This can be done with:
+----
+<head>
+ ...
+ <![CDATA[ <link rel="stylesheet" href="/css/site.css" type="text/css" >]]>
+ ...
+</head>
+----
+
diff --git a/src/site/resources/css/site.css b/src/site/resources/css/site.css
index cabfde4..360ad0f 100644
--- a/src/site/resources/css/site.css
+++ b/src/site/resources/css/site.css
@@ -20,6 +20,47 @@
* under the License.
*/
+/** start of asciidoc specific styles **/
+@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";
+
+.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
+table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
+.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
+table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
+.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
+.admonitionblock>table td.icon{text-align:center;width:80px}
+.admonitionblock>table td.icon img{max-width:none}
+.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
+.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
+.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
+.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
+.exampleblock>.content>:first-child{margin-top:0}
+.exampleblock>.content>:last-child{margin-bottom:0}
+.sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px}
+.sidebarblock>:first-child{margin-top:0}
+.sidebarblock>:last-child{margin-bottom:0}
+.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
+.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
+.literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
+
+span.icon>.fa{cursor:default}
+a span.icon>.fa{cursor:inherit}
+.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
+.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
+.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
+.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
+.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
+.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
+.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:50%;border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
+.conum[data-value] *{color:#fff!important}
+.conum[data-value]+b{display:none}
+.conum[data-value]::after{content:attr(data-value)}
+
+code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
+
+/** end of asciidoc specific styles **/
+
+
a.externalLink[href^="http"] {
background: url('../images/external-link-12x12.png') right center no-repeat;
padding-right: 18px;
diff --git a/src/site/site.xml b/src/site/site.xml
index 519b154..8a3f549 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -58,6 +58,9 @@
</custom>
<body>
<head>
+ <!-- The font-awesome is used by asciidoc -->
+ <![CDATA[ <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css">]]>
+ <!-- Google Analytics -->
<![CDATA[
<!-- Google Analytics -->
<script src='//www.google-analytics.com/analytics.js'></script>
diff --git a/src/site/slim-templates/block_table.html.slim b/src/site/slim-templates/block_table.html.slim
new file mode 100644
index 0000000..7809e05
--- /dev/null
+++ b/src/site/slim-templates/block_table.html.slim
@@ -0,0 +1,34 @@
+table(id=id
+ class=['table table-striped bodyTable', "frame-#{attr :frame, 'all'}", "grid-#{attr :grid, 'all'}", role]
+ style=[("width:#{attr :tablepcwidth}%" unless option? 'autowidth'),("float:#{attr :float}" if attr? :float)].compact.join('; '))
+ - if title?
+ caption.title =captioned_title
+ - unless (attr :rowcount).zero?
+ colgroup
+ - if option? 'autowidth'
+ - columns.each do
+ col
+ - else
+ - columns.each do |col|
+ col style="width: #{col.attr :colpcwidth}%;"
+ - [:head, :foot, :body].reject { |tblsec| rows[tblsec].empty? }.each do |tblsec|
+ - rows[tblsec].each_with_index do |row,row_index|
+ tr class=["#{tblsec == :head ? 'a': row_index%2==0 ? 'b': 'a'}"]
+ - row.each do |cell|
+ *{tag: (tblsec == :head || cell.style == :header ? 'th' : 'td'),
+ class: [ "halign-#{cell.attr :halign}", "valign-#{cell.attr :valign}"],
+ colspan: cell.colspan,
+ rowspan: cell.rowspan}
+ - if tblsec == :head
+ =cell.text
+ - else
+ - case cell.style
+ - when :asciidoc
+ div =cell.content
+ - when :verse
+ .verse =cell.text
+ - when :literal
+ .literal: pre =cell.text
+ - else
+ - cell.content.each do |text|
+ =text
\ No newline at end of file
