uid: contributing/documentation

Documentation & Website

Details about this website and the API documentation site and how to help contribute to them

Overview

The website and the api documentation source code is found in the same Git repository as the Lucene.Net code in the folder: /websites/. The website and documentation site is built with a static site generator called DocFx and all of the content/pages are created using Markdown files.

To submit changes for the website, create a Pull Request to the Lucene Git repositoriy. (See Contributing for details)

Website

Build script

To build the website and run it on your machine, run the powershell script: /websites/site/site.ps1. You don't have to pass any parameters in and it will build the site and host it at http://localhost:8080.

The script has 2 optional parameters:

-ServeDocs (default is 1) The value of 1 means it will build the docs and host the site, if 0 is specified, it will build the static site to be hosted elsewhere.
-Clean (default is 0) The value of 1 means that it will clear all caches and tool files before it builds again. This is handy if a new version of docfx is available or if there's odd things occuring with the incremental build.

File/folder structure

The file/folder structure is within /websites/site:

site.ps1 - the build script
docfx.json - the DocFx configuration file (see docfx manual for further info)
lucenetemplate/* - the custom template files to style the website
*.md - the root site content such as the index and download pages
toc.yml - these files determine the menu structures (see docfx manual for further info)
contributing/* - the Contributing section
tools/* - during the build process some tools will be downloaded which are stored here
_site - this is the exported static site that is generated

Deploy the website

The website is deployed via git
Checkout the Git repo that hosts the documentation: https://github.com/apache/lucenenet-site/tree/asf-site (ensure you have asf-site branch checked out, not master)
Copy the build output of the website to the root. The build output will be all of the files in the /websites/site/_site in your main lucene.net checked out Git repository.
Commit and push these changes
The new version of the website will be live. If the amount of new files committed is large, the new files may take some time to become live.

API Docs

Build script

To build the api docs and run it on your machine, run the powershell script: /websites/apidocs/docs.ps1. You don't have to pass any parameters in and it will build the site and host it at http://localhost:8080.

The script has 3 parameters:

-LuceneNetVersion (mandatory) This is the Lucene.Net version including pre-release information that is being built. For example: 4.8.0-beta00008. (This value will correspond to the folder and branch name where the docs get hosted, see below)
-ServeDocs (default is 1) The value of 1 means it will build the docs and host the site, if 0 is specified, it will build the static site to be hosted elsewhere.
-Clean (default is 0) The value of 1 means that it will clear all caches and tool files before it builds again. This is handy if a new version of docfx is available or if there's odd things occuring with the incremental build.

File/folder structure

The file/folder structure is within /websites/apidocs:

docs.ps1 - the build script
docfx.json - the DocFx configuration file (see docfx manual for further info)
lucenetemplate/* - the custom template files to style the website
*.md - the root site content such as the index and download pages
toc.yml - these files determine the menu structures (see docfx manual for further info)
tools/* - during the build process some tools will be downloaded which are stored here
_site - this is the exported static site that is generated

Process overview

The documentation generation is a complex process because it needs to convert the Java Lucene project‘s documentation into a usable format to produce the output Lucene.Net’s documentation.

The process overview is:

Use the JavaDocToMarkdownConverter project within the DocumentationTools.sln solution to run the conversion of the Java Lucene projects docs into a useable format for DocFx. This tool takes uses a release tag output of the Java Lucene project as it‘s source to convert against the Lucene.Net’s source.
Run the documentation build script to produce the documentation site
Publish the output to the lucenenet-site repository into a correpsonding named version directory

We don't want to manually change the converted resulting markdown files (.md) because they would get overwritten again when the conversion process is re-executed. Therefore to fix any formatting issues or customized output of the project docs, these customizations/fixes/tweaks are built directly into the conversion process itself in the JavaDocToMarkdownConverter.csproj project.

Building the docs

Checkout the Lucene.Net release tag to build the docs against
Execute the ./src/docs/convert.ps1 script and enter the current Lucene version to convert from.
- For example, for Lucene.Net 4.8.0 we are converting from the Java Lucene build release of “4.8.1” so in this case enter: 4.8.1 at the prompt or call the whole script like ./src/docs/convert.ps1 -JavaLuceneVersion 4.8.1
- This script will download and extract the Java Lucene release files, build the DocumentationTools.sln solution and execute the JavaDocToMarkdownConverter.exe
Review and commit the files changed
- Many times there will just be whitespace changes in the files especially if this process has been executed before for the same source/destination version.
- If this is a new source/destination version there will be a lot of file changes, at least one file per folder.
- If there are formatting issues or irregularities in the converted output then these will need to be addressed by making changes to the conversion tool itself JavaDocToMarkdownConverter.csproj (generally only needed for new major version releases)
Execute the ./websites/apidocs/docs.ps1 script to build and serve the api docs website locally for testing.
- Example: ./websites/apidocs/docs.ps1 -LuceneNetVersion 4.8.0-beta00008
- will serve a website on http://localhost:8080
- It will take quite a while (approx 10 minutes) to build

Publishing the docs

Checkout the Git repo that hosts the documentation: https://github.com/apache/lucenenet-site/tree/asf-site (ensure you have asf-site branch checked out, not master)
Create a new folder in this repo: /docs/[Version], for example: /docs/4.8.0-beta00008
Copy the build output of the documentation site to this new folder. The build output will be all of the files in the /websites/apidocs/_site in your main lucene.net checked out Git repository.
Commit and push these changes
The new version documentation will be live. Due to the amount of new files committed, the new files may take up to 60 minutes to become live.
Next the website needs updating which is a manual process currently:
- In the /websites/site/download folder there should be a document per release. It's normally fine to copy the document of the latest release for the same major version. For a new major version some modifications may be needed.
- Ensure the correct version number is listed in the header and the nuget download snippet.
- Update the Status and Released heading information.
- Ensure the download links are correct.
- Update the /websites/site/download/toc.yml and /websites/site/download/download.md files to include a reference to the new page which should maintain descending version order.
- Update the /websites/site/docs.md file and add a link to the new documentation for the current version which should maintain descending version order.
- Build the website and test locally, then deploy the changes
Once the website is committed/pushed, the last step is to create a named branch on the main lucenenet repository with the name: docs/[Version], for example docs/4.8.0-beta00008 based on commit of the latest (if any) changes made to the docs in the lucenenet repository on the main branch. This branch is used for linking to on the API docs “Improve this Doc” button.