SOLR-15458: Move solr-ref-guide/src/meta-docs to dev-docs; remove how…

…-to-contribute.adoc (apache#167)

dev-docs/ref-guide/jekyll.adoc

@@ -0,0 +1,136 @@
+= Working with HTML Templates
+:toc:
+// 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.
+
+The Solr Ref Guide uses Jekyll to build the HTML version of the site.
+
+== What is Jekyll?
+
+Jekyll is a static site generator, meaning that it takes some set of documents and produces HTML pages. It allows for templating of the pages, so each page has the same look and feel without having to code headers, footers, logos, etc., into every page.
+
+Jekyll is an open source project written in Ruby, online at https://jekyllrb.com/.
+
+== How We Use Jekyll
+
+The following sections describe the main features of Jekyll that you will encounter while working with the Solr Ref Guide.
+
+=== Jekyll-Asciidoctor Plugin
+We use a plugin for Jekyll from the Asciidoctor project to integrate Jekyll with Asciidoc formatted content.
+The source for the plugin is available at https://github.com/asciidoctor/jekyll-asciidoc.
+
+This plugin allows us to use Asciidoctor-style variables with Jekyll.
+
+=== _config.yml
+
+The `_config.yml` is a global configuration file that drives many of the options used when building the site (particularly in our use of Jekyll).
+
+We have template-ized `_config.yml`, so in our use of Jekyll you will find it in `solr/solr-ref-guide/src` as `_config.yml.template`.
+This allows us to define some variables during the build and use common Solr build parameters (such as project versions).
+
+=== Front Matter
+
+Front matter for Jekyll is similar to a header that defines the title of the page, and other variables that may be helpful (or even required) when rendering the page.
+
+Every document that will be converted to HTML *must* include at least the page title at the top of the page.
+Page titles are defined with a single equal sign (`=`) followed by the title that will appear at the top of the page (such as `= Topic of the Page`).
+
+Many guides to Jekyll also say that defining the `layout` in the front matter is required.
+However, since we only use one layout for all pages, we have defined this as a default.
+
+The Solr Ref Guide uses the front matter to define some custom attributes on a per-page basis:
+
+* `page-children` - ordered list of child pages, this is used to build the site navigation menu that appears to the left of each page's content.
+
+Other page-level elements can also be defined, such as an Asciidoctor attribute that should apply only to that page, but are not needed on a regular basis.
+
+The format for adding any parameter to the front matter is to use colons on both sides of the parameter, followed by the value for the parameter (such as `:page-toc: false`).
+
+==== Table of Contents
+There are some optional custom attributes that can be defined in pages to affect the Table of Contents presentation in Jekyll:
+
+`toclevels`::
+Changes how "deep" the TOC will be in terms of nested section/sub-section titles (default = `2`). Example: `:toclevels: 1`.
+
+`page-show-toc`::
+If this is `false`, then no TOCs will be generated for the page at all.
+The default is `true`, so can usually be left undefined.
+Example `:page-show-toc: false`.
+
+
+=== Layouts
+
+Layouts define the "look and feel" of each page.
+Jekyll uses https://shopify.github.io/liquid/[Liquid] for page templates.
+
+For our implementation of Jekyll, layouts are found in `solr-ref-guide/src/_layouts`.
+
+We currently use the `_layouts/default.html` layout for overall page structure, for almost all pages and `_layouts/page.html` for the page-level content.
+The `page.html` layout is inserted into the `default.html` layout.
+
+The main page (`index.html`) of the Ref Guide uses the `_layouts/home.html` layout.
+It also still uses `_layouts/page.html` for the page-level content.
+This is done because `index.html` has some special formatting and rules for how to define the page.
+
+=== Includes
+
+Include files are (usually) small HTML files that are pulled into a layout when a page is being built.
+They are Liquid templates that define an area of the page.
+This allows flexibility across layouts - all pages can have the same header without duplicating code, but different pages could have different menu options.
+
+Include files that we use define the top navigation, the page header, and the page footer.
+
+For our implementation of Jekyll, include files are found in `solr-ref-guide/src/_includes`.
+
+=== Data Files
+
+Data files include data such as lists that should be included in each page.
+The left-hand navigation menu is an example of a data file.
+However, in our build, the navigation is built from the `page-children` hierarchies defined on parent pages.
+
+For our implementation of Jekyll, data files are found in `solr-ref-guide/src/_data`.
+
+=== Asciidoctor Slim Templates
+
+Jekyll creates all of the page elements we do not define in each `.adoc` file: the header, footer, top nav, sidebar nav, and other parts of the page that we don't worry about as we write the content of a page.
+
+Asciidoctor converts the content in each `.adoc` file into HTML and inserts it into the Jekyll page layout we have defined (see <<Layouts>>) to make the individual HTML files that make up the Ref Guide.
+
+While we have unlimited control over styling page content via CSS, without creating custom Asciidoctor-specific plugins or templates there is little out-of-the-box control over the elements, classes, etc., that make up the HTML pages.
+
+In order to better support HTML5, we have customized Asciidoc's default conversion with templates found in the `_templates` directory.
+These templates use http://slim-lang.com/[Slim] as the template engine.
+
+Since these templates dictate the very structure of the HTML of our content, customizing these should only be attempted in rare instances and with extensive testing for unforeseen impacts.
+
+=== Using Bootstrap
+
+The HTML files include https://getbootstrap.com/docs/4.1/[Bootstrap] (v4.1.3 as of April 2020, see `_includes/head.html` to confirm the Bootstrap version currently being used), so all of the components of Bootstrap are available.
+
+The design of the Ref Guide makes extensive use of Bootstrap classes to layout the page via the Liquid templates and our customized Asciidoctor templates.
+
+When we want to use additional components of Boostrap that require specific HTML constructs, we must define those within the page content itself (using either `<div>` elements in the content or with Asciidoctor's roles, discussed in the next section).
+
+
+== Building the HTML Site
+
+A Gradle target `gradlew checkSite` will build the full HTML site (found in `solr/solr-ref-guide/build/html-site`).
+
+This target builds the navigation for the left-hand menu, and converts all `.adoc` files to `.html`, including navigation and inter-document links.
+
+The `checkSite` target also checks that all inter-doc references are correct and resolvable.
+See `solr/solr-ref-guide/tools/CheckLinksAndAnchors.java` for details of what that tool does to validate content.

solr/solr-ref-guide/src/meta-docs/publish.adoc → dev-docs/ref-guide/publish.adoc

@@ -1,4 +1,5 @@
 = Ref Guide Publication Process
+:toc:
 // 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
@@ -21,33 +22,39 @@ This section details how to build the Guide for publication.
 == Guide Publication Overview
 
 . Build and publish the DRAFT version.
-. Continue to update docs as needed while Lucene/Solr artifact VOTE thread is ongoing.
+This is usually done as soon as the RC for a release is available.
+. Continue to update docs as needed while Solr artifact VOTE thread is ongoing.
 . After VOTE has passed, build and publish final version to overwrite DRAFT watermarked pages.
 
 == Pre-Requisites
 
 In order to build the Ref Guide, you must have the following:
 
-* You have checked out the Lucene/Solr source code on the machine you will be doing the release from.
-* You have Subversion installed. This is needed for committing the HTML files to the production website repo.
+* You have checked out the Solr source code on the machine you will be doing the release from.
+* You have Subversion installed.
+This is needed for committing the HTML files to the production website repo.
 * All builds must be done from the release branch the Guide is for.
 
-NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jenkins] for several branches. However, these HTML pages will have the `DRAFT` status noted in them and are not suitable for final production publishing.
+NOTE: Build jobs are done by https://ci-builds.apache.org/job/Solr/[Jenkins] for relevant recent branches.
+The latest builds are stored in the https://nightlies.apache.org/solr/draft-guides/[ASF nightlies server].
+However, these HTML pages will have the `DRAFT` status noted in them and are not suitable for final production publishing.
 
 All dependencies for the build will be installed by Gradle, no local dependencies are required.
 
 == Build the DRAFT Guide
 
-The build process generates the page hierarchy and builds the HTML pages with custom templates the Lucene/Solr project has defined.
+The build process generates the page hierarchy and builds the HTML pages with custom templates the Solr project has defined.
 
 To build the HTML, from the top level of the project, run:
 
 [source,bash]
 $ ./gradlew clean solr:solr-ref-guide:buildSite
 
-This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <<Publish the Final Guide>> for steps to produce final production-ready HTML pages.
+This will produce pages with a DRAFT watermark across them.
+While these are fine for initial DRAFT publication, see the section <<Publish the Final Guide>> for steps to produce final production-ready HTML pages.
 
-The resulting Guide will be in `solr/solr-ref-guide/build`. The HTML files themselves will be in `solr/solr-ref-guide/build/html-site`.
+The resulting Guide will be in `solr/solr-ref-guide/build`.
+The HTML files themselves will be in `solr/solr-ref-guide/build/html-site`.
 
 == Upload to the Website
 
@@ -56,8 +63,8 @@ Push the Guide directly to production via Subversion `import` from where you bui
 [source,bash]
 svn -m "Add Ref Guide for Solr 7.7" import <checkoutroot>/solr/solr-ref-guide/build/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/7_7
 
-Confirm you can browse to Guide manually by going to the new URL. For example:
-https://solr.apache.org/guide/7_7
+Confirm you can browse to Guide manually by going to the new URL.
+For example: https://solr.apache.org/guide/7_7
 
 == Publish the Final Guide
 
@@ -69,12 +76,15 @@ Since the Guide has already been uploaded to SVN, you need to overwrite the exis
 
 *Build Production Guide*
 
-Build the Guide locally with a parameter for the Guide version. This requires the same <<Pre-Requisites,pre-requisites>> from above.
+Build the Guide locally with a parameter for the Guide version.
+This requires the same <<Pre-Requisites,pre-requisites>> from above.
 
 [source,bash]
 $ ./gradlew solr:solr-ref-guide:buildSite -PsolrGuideDraft=false
 
-IMPORTANT: The `-PsolrGuideDraft` system property is optional if you build drafts locally or as pre-publication DRAFTs (i.e., not for publication). By default the build system assumes this is a `DRAFT` build which will have a DRAFT watermark and other labels on the pages. Including the `-PsolrGuideDraft=false` property ensures the DRAFT watermark and labels are removed from the HTML files.
+IMPORTANT: The `-PsolrGuideDraft` system property is optional if you build drafts locally or as pre-publication DRAFTs (i.e., not for publication).
+By default the build system assumes this is a `DRAFT` build which will have a DRAFT watermark and other labels on the pages.
+Including the `-PsolrGuideDraft=false` property ensures the DRAFT watermark and labels are removed from the HTML files.
 
 *Pull Production Repo and Upload New Files*
 
@@ -84,33 +94,38 @@ IMPORTANT: The `-PsolrGuideDraft` system property is optional if you build draft
 $ svn co https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/<dir>
 +
 * This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "7_7"). You can provide a better name locally if you prefer by adding it to the end of the command shown above.
-* Don't shortcut this and download the whole production website. It will take an incredibly long time and that will feel like _forever_.
-. Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the Guide for Solr 7.7, we'd do `cp -r ./solr/solr-ref-guide/build/html-site 7_7/.`
-. Use `svn status` to see the files modified. If there are any pages added or deleted, use `svn add <file>` or `svn rm <file>` as needed.
+* Don't shortcut this and download the whole production website.
+It will take an incredibly long time and that will feel like _forever_.
+. Copy the files from the build location to the checked out Guide directory.
+For example, if we needed to replace the Guide for Solr 7.7, we'd do `cp -r ./solr/solr-ref-guide/build/html-site 7_7/.`
+. Use `svn status` to see the files modified.
+If there are any pages added or deleted, use `svn add <file>` or `svn rm <file>` as needed.
 . Commit the changes: `svn commit -m "Update production 7.7 Ref Guide"`
 
 *Verify Upload Successful*
 
 Spot-check a few pages to verify that the DRAFT watermark is gone, and also
- that Solr Javadocs link back to Lucene's correctly (the UpdateRequestProcessor
- page has a lot of Javadoc links).
+that Solr Javadocs link back to Lucene's correctly (the UpdateRequestProcessor
+page has a lot of Javadoc links).
 
 === Link to the New Version from Solr Website
 
 The only edit we need to do in the website itself is adding a link to the latest guide to /solr/guide.
 
 *Edit guide.md in staging*
 
-. Look at https://lucene.staged.apache.org/solr/guide and see if the RM already has updated it. If not, continue
-. You can check out and push changes or edit the file directly in GitHub: https://github.com/apache/lucene-site/blob/master/content/pages/solr/guide.md by clicking the edit button and then adding a commit message.
+. Look at https://solr.staged.apache.org/guide and see if the RM already has updated it.
+If not, continue
+. You can check out and push changes or edit the file directly in GitHub: https://github.com/apache/solr-site/blob/main/content/pages/guide.md by clicking the edit button and then adding a commit message.
 . Verify that the staged version looks good (the link will not work in staging though)
 
 *Publish the changes to production*
 
-You can use your favourite git client to merge leader into branch `production`. Or you can use GitHub website:
+You can use your favourite git client to merge leader into branch `production`.
+Or you can use GitHub website:
 
-. Make a new pull request from https://github.com/apache/lucene-site/compare/production%2E%2E%2Emaster
+. Make a new pull request from https://github.com/apache/solr-site/compare/production%2E%2E%2Emain
 . Note: If there are other changes staged, you will see those as well if you merge `master` into `production`
 . Click the "Merge" button on the PR
 
-The ordinary Solr release process will update the `LUCENE_LATEST_RELEASE` property of the website, which will ensure that Ref Guide URLs without a version in the path (e.g., `/solr/guide/mypage.adoc`) will automatically redirect to the latest Guide.
+The ordinary Solr release process will update the `SOLR_LATEST_RELEASE` property of the website, which will ensure that Ref Guide URLs without a version in the path (e.g., `/guide/mypage.adoc`) will automatically redirect to the latest Guide.

solr/solr-ref-guide/src/index.adoc

@@ -20,8 +20,7 @@
     client-apis, \
     further-assistance, \
     solr-glossary, \
-    errata, \
-    how-to-contribute
+    errata
 :page-notitle:
 :page-show-toc: false
 :page-layout: home