Google Git
Sign in
apache / lucenenet-site / refs/heads/asf-site / . / contributing / documentation.html
blob: 5f0e0dc4087182b28e5548f7cffc5e34e787e7ec [file] [log] [blame]
<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Documentation &amp; Website | Apache Lucene.NET 4.8.0 </title>
<meta name="viewport" content="width=device-width">
<meta name="title" content="Documentation &amp; Website | Apache Lucene.NET 4.8.0 ">
<meta name="generator" content="docfx 2.58.0.0">
<link rel="shortcut icon" href="../logo/favicon.ico">
<link rel="stylesheet" href="../styles/docfx.vendor.css">
<link rel="stylesheet" href="../styles/docfx.css">
<link rel="stylesheet" href="../styles/main.css">
<meta property="docfx:navrel" content="../toc.html">
<meta property="docfx:tocrel" content="toc.html">
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:400,700%7CMerriweather%7CRoboto+Mono">
<link rel="stylesheet" href="/styles/site.css">
</head>
<body data-spy="scroll" data-target="#affix" data-offset="120">
<span id="forkongithub"><a href="https://github.com/apache/lucenenet" target="_blank">Fork me on GitHub</a></span>
<div id="wrapper">
<header>
<nav id="autocollapse" class="navbar ng-scope" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="../index.html">
<img id="logo" class="svg" src="../logo/lucene-net-color.png" alt="">
</a>
</div>
<div class="collapse navbar-collapse" id="navbar">
<form class="navbar-form navbar-right" role="search" id="search">
<div class="form-group">
<input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
</div>
</form>
</div>
</div>
</nav>
<div class="subnav navbar navbar-default">
<div class="container hide-when-search" id="breadcrumb">
<ul class="breadcrumb">
<li></li>
</ul>
</div>
</div>
</header>
<div role="main" class="container body-content hide-when-search">
<div class="sidenav hide-when-search">
<a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
<div class="sidetoggle collapse" id="sidetoggle">
<div id="sidetoc"></div>
</div>
</div>
<div class="article row grid-right">
<div class="col-md-10">
<article class="content wrap" id="_content" data-uid="contributing/documentation">
<h1 id="documentation--website">Documentation &amp; Website</h1>
<hr>
<p><em>Details about this website and the API documentation site and how to help contribute to them</em></p>
<h2 id="overview">Overview</h2>
<p>The website and the api documentation source code is found in the same Git repository as the Lucene.Net code in the folder: <code>./websites/</code>. The website and documentation site is built with a static site generator called <a href="https://dotnet.github.io/docfx/">DocFx</a> and all of the content/pages are created using Markdown files.</p>
<p>To submit changes for the website, create a Pull Request to the <a href="https://github.com/apache/lucenenet">Lucene Git repositoriy</a>. (See <a class="xref" href="index.html#submit-a-pull-request">Contributing</a> for details)</p>
<h2 id="website">Website</h2>
<h3 id="build-script">Build script</h3>
<p>To build the website and run it on your machine, run the Powershell script: <code>./websites/site/site.ps1</code> with the <code>-ServeDocs</code> flag. For example:</p>
<pre><code>./websites/site/site.ps1 -ServeDocs
</code></pre>
<p>When executed this will build the site and host it at <a href="http://localhost:8081">http://localhost:8081</a>.</p>
<p>To build the website for release, run the script:</p>
<pre><code>./websites/site/site.ps1
</code></pre>
<p>This will build the site with all live parameters configured correctly and output the built static site into the <code>_site</code> folder.</p>
<p>The script parameters are:</p>
<ul>
<li><code>-ServeDocs</code> <em>(optional)</em> 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.</li>
<li><code>-Clean</code> <em>(optional)</em> 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.</li>
</ul>
<h3 id="filefolder-structure">File/folder structure</h3>
<p>The file/folder structure is within <code>./websites/site</code>:</p>
<ul>
<li><code>site.ps1</code> - the build script</li>
<li><code>docfx.json</code> - the DocFx configuration file <em>(see docfx manual for further info)</em></li>
<li><code>lucenetemplate/*</code> - the custom template files to style the website</li>
<li><code>*.md</code> - the root site content such as the index and download pages</li>
<li><code>toc.yml</code> - these files determine the menu structures <em>(see docfx manual for further info)</em></li>
<li><code>contributing/*</code> - the Contributing section</li>
<li><code>tools/*</code> - during the build process some tools will be downloaded which are stored here</li>
<li><code>_site</code> - this is the exported static site that is generated</li>
</ul>
<h3 id="deploy-the-website">Deploy the website</h3>
<ul>
<li>The website is deployed via GitHub and is hosted by static files here: <a href="https://github.com/apache/lucenenet-site/tree/asf-site">https://github.com/apache/lucenenet-site/tree/asf-site</a> <em>(ensure you have <code>asf-site</code> branch checked out, not <code>master</code>)</em></li>
<li>Any file changes made in the <code>master</code> branch of the Lucene.Net repository under the path <code>./websites/site/*</code> will trigger a GitHub action to build the site and publish a Pull Request to the <a href="https://github.com/apache/lucenenet-site">https://github.com/apache/lucenenet-site</a> repository where it can be accepted</li>
<li>Review and merge the Pull Request. 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.</li>
</ul>
<h2 id="api-docs">API Docs</h2>
<h3 id="build-script-1">Build script</h3>
<p>To build the api docs and run it on your machine, run the Powershell script: <code>./websites/apidocs/docs.ps1</code>. For example:</p>
<pre><code>./websites/apidocs/docs.ps1 -ServeDocs -LuceneNetVersion 4.8.0-beta00008 -BaseUrl http://localhost:8080
</code></pre>
<p>When executed this will build the site and host it at <a href="http://localhost:8080">http://localhost:8080</a>. <em>(Ensure to pass in the current version of Lucene.Net you are building.)</em></p>
<p>To build the api docs for release, run the script:</p>
<pre><code>./websites/apidocs/docs.ps1 -LuceneNetVersion 4.8.0-beta00008
</code></pre>
<p>This will build the site with all live parameters configured correctly and output the built static site into the <code>_site</code> folder.</p>
<p>The script parameters are:</p>
<ul>
<li><code>-LuceneNetVersion</code> <em>(mandatory)</em> This is the Lucene.Net version including pre-release information that is being built. For example: <code>4.8.0-beta00008</code>. <em>(This value will correspond to the folder and branch name where the docs get hosted, see below)</em></li>
</ul>
<ul>
<li><code>-ServeDocs</code> <em>(optional)</em> 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.</li>
<li><code>-Clean</code> <em>(optional)</em> 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.</li>
<li><code>-DisableMetaData</code> <em>(optional)</em> 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.</li>
<li><code>-DisableBuild</code> <em>(optional)</em> A boolean switch. If present it will disable the site building operation of the docs build. Can be handy when debugging the docs build.</li>
<li><code>-DisablePlugins</code> <em>(optional)</em> A boolean switch. If present it will not build the custom Lucene.Net <code>DocumentationTools.sln</code> docsfx plugins and exclude them from the build.</li>
<li><code>-LogLevel</code> <em>(optional)</em> Default is Warning. Options are: Diagnostic, Verbose, Info, Warning, Error.</li>
<li><code>-BaseUrl</code> <em>(optional)</em> Default is <a href="https://lucenenet.apache.org/docs/">https://lucenenet.apache.org/docs/</a>. Used to set the base URL of the docfx xref map files for cross linking between project builds.</li>
</ul>
<h3 id="filefolder-structure-1">File/folder structure</h3>
<p>The file/folder structure is within <code>./websites/apidocs</code>:</p>
<ul>
<li><code>docs.ps1</code> - The build script</li>
<li><code>docfx.*.json</code> - The DocFx configuration files <em>(see docfx manual for further info)</em>
<ul>
<li><code>docfx.{library}.json</code> - Where {library} is an individual Lucene.NET project (i.e. <code>codecs</code>). Each library is built as it's own individual DocFx site and it's xref maps are exported to file to be shared between DocFx builds.</li>
<li><code>docfx.global.json</code> - Each library DocFx json references this file for global metadata. This is where all global metadata such as Title, Logo, Footer, etc... are declared.</li>
<li><code>docfx.global.subsite.json</code> - Each library DocFx json references this file for global metadata which denotes the <a href="https://dotnet.github.io/docfx/tutorial/intro_template.html#system-generated-properties"><code>_rel</code></a> (The relative path of the root output folder from current output file. i.e. the base URL). For example: <code>https://lucenenet.apache.org/docs/4.8.0-beta00009/</code>.</li>
<li><code>docfx.site.json</code> - Once each library is built and it's xref maps are exported, the main documentation site container is built with this definition.</li>
</ul>
</li>
<li><code>lucenetemplate/*</code> - The custom template files to style the website</li>
<li><code>*.md</code> - The root site content such as the index and download pages</li>
<li><code>toc.yml</code> - These files determine the menu structures <em>(see docfx manual for further info)</em></li>
<li><code>tools/*</code> - During the build process some tools will be downloaded which are stored here</li>
<li><code>_site</code> - This is the exported static site that is generated</li>
</ul>
<h3 id="java-to-markdown-converter">Java to Markdown converter</h3>
<p>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.</p>
<p>The <code>JavaDocToMarkdownConverter</code> dotnet tool to is used to convert the Java Lucene project's docs into a useable format for DocFx. This tool uses a release tag output of the Java Lucene project as it's source to convert against the Lucene.NET's source. This tool must <strong>only</strong> be executed against the current documentation branch, for example in 4.8.0 it is: <code>docs/markdown-converted/4.8.1</code>. This conversion process does not need to be executed everytime the docs are built, it is executed rarely when:</p>
<ul>
<li>A new major or minor version of Lucene.Net is created and the conversion needs to be re-executed again the Java Lucene source. In this case a new documentation branch should be created from the previous documentation branch.</li>
<li>Updates to the <code>JavaDocToMarkdownConverter</code> are made and the conversion needs to be re-executed.</li>
</ul>
<h4 id="manual-execution">Manual execution</h4>
<p>To use the dotnet tool you must download the current tag of the Java Lucene project, for example: <a href="https://github.com/apache/lucene-solr/releases/tag/releases%2Flucene-solr%2F4.8.1">&quot;4.8.1&quot;</a></p>
<p>Then install the tool:</p>
<pre><code>dotnet tool install javadoc2markdown --add-source https://pkgs.dev.azure.com/lucene-net/_packaging/lucene-net-tools/nuget/v3/index.json --tool-path ./
</code></pre>
<p>Then run the command:</p>
<pre><code>javadoc2markdown &lt;LUCENE DIRECTORY&gt; &lt;LUCENENET DIRECTORY&gt;
</code></pre>
<p>Where <code>&lt;LUCENE DIRECTORY&gt;</code> is the <code>lucene</code> sub folder location of the Java Lucene tag downloaded above. The <code>&lt;LUCENENET DIRECTORY&gt;</code> is the folder of your locally checked out Lucene.Net git repository of the documentation tag (i.e. <code>docs/markdown-converted/4.8.1</code>).</p>
<h4 id="automated-execution">Automated execution</h4>
<p>A powershell script has been created to automate the above. Execute the <code>./src/docs/convert.ps1</code> 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 <a href="https://github.com/apache/lucene-solr/releases/tag/releases%2Flucene-solr%2F4.8.1">&quot;4.8.1&quot;</a> so in this case enter: 4.8.1 at the prompt or call the whole script like <code>./src/docs/convert.ps1 -JavaLuceneVersion 4.8.1</code></p>
<h4 id="review-commit-and-merge">Review, commit and merge</h4>
<p>Once the conversion is done, review, commit and push those changes. 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 <strong>lot</strong> 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 (generally only needed for new major version releases).</p>
<p>Once pushed, you can merge those changes to the <code>master</code> branch. Doing this may trigger merge conflicts because the documentation files may have been manually edited. In these cases you will need to manually review and fix the merge conflicts with your favorite merge tool ensuring that the most recent manual changes done are kept.</p>
<h4 id="tool-info">Tool info</h4>
<ul>
<li><a href="https://github.com/NightOwl888/lucenenet-javadoc2markdown">Source code is here</a></li>
<li>Tool name: <code>javadoc2markdown</code></li>
<li><a href="https://dev.azure.com/lucene-net/Lucene.NET/_packaging?_a=feed&amp;feed=lucene-net-tools">NuGet feed here</a></li>
</ul>
<h3 id="publishing-the-docs">Publishing the docs</h3>
<div class="NOTE">
<h5>Note</h5>
<p>Before publishing, when testing locally ensure that both the &quot;Improve this doc&quot; button on each documentation page and the &quot;View Source&quot; button (when viewing a Class) links correctly to the newly created version branch on GitHub.</p>
</div>
<ul>
<li><p>Create and checkout a new branch based on the release tag on the main branch with the name: <code>docs/[Version]</code>, for example <code>docs/4.8.0-beta00008</code>. This branch is used for linking to on the API docs &quot;Improve this Doc&quot; and &quot;View Source&quot; buttons. Then build the docs, for example: <code>./websites/apidocs/docs.ps1 -LuceneNetVersion 4.8.0-beta00008</code> (For testing <a href="#build-script-1">see above</a>).</p>
</li>
<li><p>Commit and push any changes you may need to make for the API docs.</p>
</li>
<li><p>Checkout the Git repo that hosts the documentation: <a href="https://github.com/apache/lucenenet-site/tree/asf-site">https://github.com/apache/lucenenet-site/tree/asf-site</a> <em>(ensure you have <code>asf-site</code> branch checked out, not <code>master</code>)</em>.</p>
</li>
<li><p>Create a new folder in this repo: <code>/docs/[Version]</code>, for example: <code>/docs/4.8.0-beta00008</code>.</p>
</li>
<li><p>Copy the build output of the documentation site to this new folder. The build output will be all of the files in the <code>./websites/apidocs/_site</code> in your main Lucene.NET checked out Git repository. Commit and push these changes.</p>
</li>
<li><p>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.</p>
</li>
<li><p>Next the website needs updating which is a manual process currently:</p>
<ul>
<li>In the <code>./websites/site/download</code> 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.</li>
<li>Ensure the correct version number is listed in the header and the NuGet download snippet.</li>
<li>Update the <code>Status</code> and <code>Released</code> heading information.</li>
<li>Ensure the download links are correct.</li>
<li>Update the <code>./websites/site/download/toc.yml</code> and <code>./websites/site/download/download.md</code> files to include a reference to the new page which should maintain descending version order.</li>
<li>Update the <code>./websites/site/docs.md</code> file and add a link to the new documentation for the current version which should maintain descending version order.</li>
<li><a href="#website">Build the website</a> and test locally, then deploy the changes</li>
</ul>
</li>
</ul>
</article>
</div>
<div class="hidden-sm col-md-2" role="complementary">
<div class="sideaffix">
<div class="contribution">
<ul class="nav">
<li>
<a href="https://github.com/apache/lucenenet/blob/master/websites/site/contributing/documentation.md/#L1" class="contribution-link">Improve this Doc</a>
</li>
</ul>
</div>
<nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
<h5>In This Article</h5>
<div></div>
</nav>
</div>
</div>
</div>
</div>
<footer>
<div class="grad-bottom"></div>
<div class="footer">
<div class="container">
<span class="pull-right">
<a href="#top">Back to top</a>
</span>
Copyright &copy; 2022 The Apache Software Foundation, Licensed under the <a href='http://www.apache.org/licenses/LICENSE-2.0' target='_blank'>Apache License, Version 2.0</a><br> <small>Apache Lucene.Net, Lucene.Net, Apache, the Apache feather logo, and the Apache Lucene.Net project logo are trademarks of The Apache Software Foundation. <br>All other marks mentioned may be trademarks or registered trademarks of their respective owners.</small>
</div>
</div>
</footer>
</div>
<script type="text/javascript" src="../styles/docfx.vendor.js"></script>
<script type="text/javascript" src="../styles/docfx.js"></script>
<script type="text/javascript" src="../styles/main.js"></script>
</body>
</html>