Details about this website and the API documentation site and how to help contribute to them
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)
To build the website and run it on your machine, run the Powershell script: /websites/site/site.ps1
with the -ServeDocs
flag. For example:
/websites/site/site.ps1 -ServeDocs
When executed this will build the site and host it at http://localhost:8081.
To build the website for release, run the script:
/websites/site/site.ps1
This will build the site with all live parameters configured correctly and output the built static site into the _site
folder.
The script parameters are:
-ServeDocs
(optional) A boolean switch. If present, it will build the docs and host the site. If not present it will build the static site to be hosted elsewhere.-Clean
(optional) A boolean switch. If present, 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 occurring with the incremental build.The file/folder structure is within /websites/site
:
site.ps1
- the build scriptdocfx.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 pagestoc.yml
- these files determine the menu structures (see docfx manual for further info)contributing/*
- the Contributing sectiontools/*
- during the build process some tools will be downloaded which are stored here_site
- this is the exported static site that is generatedasf-site
branch checked out, not master
)/websites/site/_site
in your main Lucene.NET checked out Git repository.To build the api docs and run it on your machine, run the Powershell script: /websites/apidocs/docs.ps1
. For example:
/websites/apidocs/docs.ps1 -ServeDocs -LuceneNetVersion 4.8.0-beta00008 -BaseUrl http://localhost:8080
When executed this will build the site and host it at http://localhost:8080. (Ensure to pass in the current version of Lucene.Net you are building.)
To build the api docs for release, run the script:
/websites/apidocs/docs.ps1 -LuceneNetVersion 4.8.0-beta00008
This will build the site with all live parameters configured correctly and output the built static site into the _site
folder.
The script parameters are:
-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
(optional) A boolean switch. If present, it will build the docs and host the site. If not present it will build the static site to be hosted elsewhere.-Clean
(optional) A boolean switch. If present, 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 occurring with the incremental build.-DisableMetaData
(optional) A boolean switch. If present it will disable the docfx metadata build operation of the docs build. Can be handy when debugging the docs build.-DisableBuild
(optional) A boolean switch. If present it will disable the site building operation of the docs build. Can be handy when debugging the docs build.-DisablePlugins
(optional) A boolean switch. If present it will not build the custom Lucene.Net DocumentationTools.sln
docsfx plugins and exclude them from the build.-LogLevel
(optional) Default is Warning. Options are: Diagnostic, Verbose, Info, Warning, Error.-BaseUrl
(optional) Default is https://lucenenet.apache.org/docs/. Used to set the base URL of the docfx xref map files for cross linking between project builds.The file/folder structure is within /websites/apidocs
:
docs.ps1
- the build scriptdocfx.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 pagestoc.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 generatedThe 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:
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.lucenenet-site
repository into a corresponding named version directoryWe 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.
./src/docs/convert.ps1
script and enter the current Lucene version to convert from../src/docs/convert.ps1 -JavaLuceneVersion 4.8.1
DocumentationTools.sln
solution and execute the JavaDocToMarkdownConverter.exe
JavaDocToMarkdownConverter.csproj
(generally only needed for new major version releases)./websites/apidocs/docs.ps1
script to build and serve the api docs website locally for testing../websites/apidocs/docs.ps1 -LuceneNetVersion 4.8.0-beta00008
asf-site
branch checked out, not master
)/docs/[Version]
, for example: /docs/4.8.0-beta00008
/websites/apidocs/_site
in your main Lucene.NET checked out Git repository./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.Status
and Released
heading information./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./websites/site/docs.md
file and add a link to the new documentation for the current version which should maintain descending version order.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.