This is an automated email from the ASF dual-hosted git repository. shazwazza pushed a commit to branch docs-poc in repository https://gitbox.apache.org/repos/asf/lucenenet.git
commit 90d9b0d8ddf2903cf1e4e02de43937dae9878f74 Author: Shannon <[email protected]> AuthorDate: Wed Jun 17 13:22:01 2020 +1000 Gets the "Core" subsite working (finally), now to see if we can get more functional with the header menu --- src/Lucene.Net/overview.md | 258 +++++++++++---------- .../partials/breadcrumb.tmpl.partial | 16 ++ .../apidocs/LuceneTemplateAssets/styles/main.css | 10 + websites/apidocs/docfx.core.json | 12 +- websites/apidocs/docfx.global.json | 14 ++ websites/apidocs/docfx.global.subsite.json | 3 + websites/apidocs/docfx.site.json | 3 + websites/apidocs/docs.ps1 | 29 ++- websites/apidocs/toc.yml | 2 +- websites/apidocs/toc/core/toc.yml | 6 +- websites/apidocs/toc/subsite/toc.yml | 6 - websites/apidocs/toc/toc.yml | 2 + 12 files changed, 216 insertions(+), 145 deletions(-) diff --git a/src/Lucene.Net/overview.md b/src/Lucene.Net/overview.md index 169769f..0d50298 100644 --- a/src/Lucene.Net/overview.md +++ b/src/Lucene.Net/overview.md @@ -1,125 +1,135 @@ ---- -uid: Lucene.Net -title: Lucene.Net -summary: *content ---- - -<!-- - 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. ---> - -Apache Lucene is a high-performance, full-featured text search engine library. Here's a simple example how to use Lucene for indexing and searching (using JUnit to check if the results are what we expect): - -<!-- = Java2Html Converter 5.0 [2006-03-04] by Markus Gebhard [email protected] = --> - - Analyzer analyzer = new StandardAnalyzer(Version.LUCENE_CURRENT); +--- +uid: Lucene.Net +title: Lucene.Net +summary: *content +--- + +<!-- + 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. +--> + +Apache Lucene is a high-performance, full-featured text search engine library. Here's a simple example how to use Lucene for indexing and searching (using JUnit to check if the results are what we expect): + +<!-- = Java2Html Converter 5.0 [2006-03-04] by Markus Gebhard [email protected] = --> + + Analyzer analyzer = new StandardAnalyzer(Version.LUCENE_CURRENT); - // Store the index in memory: - Directory directory = new RAMDirectory(); - // To store an index on disk, use this instead: - //Directory directory = FSDirectory.open("/tmp/testindex"); - IndexWriterConfig config = new IndexWriterConfig(Version.LUCENE_CURRENT, analyzer); - IndexWriter iwriter = new IndexWriter(directory, config); - Document doc = new Document(); - String text = "This is the text to be indexed."; - doc.add(new Field("fieldname", text, TextField.TYPE_STORED)); - iwriter.addDocument(doc); - iwriter.close(); - - // Now search the index: - DirectoryReader ireader = DirectoryReader.open(directory); - IndexSearcher isearcher = new IndexSearcher(ireader); - // Parse a simple query that searches for "text": - QueryParser parser = new QueryParser(Version.LUCENE_CURRENT, "fieldname", analyzer); - Query query = parser.parse("text"); - ScoreDoc[] hits = isearcher.search(query, null, 1000).scoreDocs; - assertEquals(1, hits.length); - // Iterate through the results: - for (int i = 0; i < hits.length;="" i++)="" {="" document="" hitdoc="isearcher.doc(hits[i].doc);" assertequals("this="" is="" the="" text="" to="" be="" indexed.",="" hitdoc.get("fieldname"));="" }="" ireader.close();=""> - -The Lucene API is divided into several packages: - -* __<xref:Lucene.Net.Analysis>__ -defines an abstract [Analyzer](xref:Lucene.Net.Analysis.Analyzer) -API for converting text from a {@link java.io.Reader} -into a [TokenStream](xref:Lucene.Net.Analysis.TokenStream), -an enumeration of token [Attribute](xref:Lucene.Net.Util.Attribute)s. -A TokenStream can be composed by applying [TokenFilter](xref:Lucene.Net.Analysis.TokenFilter)s -to the output of a [Tokenizer](xref:Lucene.Net.Analysis.Tokenizer). -Tokenizers and TokenFilters are strung together and applied with an [Analyzer](xref:Lucene.Net.Analysis.Analyzer). -[analyzers-common](../analyzers-common/overview-summary.html) provides a number of Analyzer implementations, including -[StopAnalyzer](../analyzers-common/org/apache/lucene/analysis/core/StopAnalyzer.html) -and the grammar-based [StandardAnalyzer](../analyzers-common/org/apache/lucene/analysis/standard/StandardAnalyzer.html). - -* __<xref:Lucene.Net.Codecs>__ -provides an abstraction over the encoding and decoding of the inverted index structure, -as well as different implementations that can be chosen depending upon application needs. - -* __<xref:Lucene.Net.Documents>__ -provides a simple [Document](xref:Lucene.Net.Documents.Document) -class. A Document is simply a set of named [Field](xref:Lucene.Net.Documents.Field)s, -whose values may be strings or instances of {@link java.io.Reader}. - -* __<xref:Lucene.Net.Index>__ -provides two primary classes: [IndexWriter](xref:Lucene.Net.Index.IndexWriter), -which creates and adds documents to indices; and <xref:Lucene.Net.Index.IndexReader>, -which accesses the data in the index. - -* __<xref:Lucene.Net.Search>__ -provides data structures to represent queries (ie [TermQuery](xref:Lucene.Net.Search.TermQuery) -for individual words, [PhraseQuery](xref:Lucene.Net.Search.PhraseQuery) -for phrases, and [BooleanQuery](xref:Lucene.Net.Search.BooleanQuery) -for boolean combinations of queries) and the [IndexSearcher](xref:Lucene.Net.Search.IndexSearcher) -which turns queries into [TopDocs](xref:Lucene.Net.Search.TopDocs). -A number of [QueryParser](../queryparser/overview-summary.html)s are provided for producing -query structures from strings or xml. - -* __<xref:Lucene.Net.Store>__ -defines an abstract class for storing persistent data, the [Directory](xref:Lucene.Net.Store.Directory), -which is a collection of named files written by an [IndexOutput](xref:Lucene.Net.Store.IndexOutput) -and read by an [IndexInput](xref:Lucene.Net.Store.IndexInput). -Multiple implementations are provided, including [FSDirectory](xref:Lucene.Net.Store.FSDirectory), -which uses a file system directory to store files, and [RAMDirectory](xref:Lucene.Net.Store.RAMDirectory) -which implements files as memory-resident data structures. - -* __<xref:Lucene.Net.Util>__ -contains a few handy data structures and util classes, ie [OpenBitSet](xref:Lucene.Net.Util.OpenBitSet) -and [PriorityQueue](xref:Lucene.Net.Util.PriorityQueue). - -To use Lucene, an application should: - -1. Create [Document](xref:Lucene.Net.Documents.Document)s by -adding -[Field](xref:Lucene.Net.Documents.Field)s; - -2. Create an [IndexWriter](xref:Lucene.Net.Index.IndexWriter) -and add documents to it with [AddDocument](xref:Lucene.Net.Index.IndexWriter#methods); - -3. Call [QueryParser.parse()](../queryparser/org/apache/lucene/queryparser/classic/QueryParserBase.html#parse(java.lang.String)) -to build a query from a string; and - -4. Create an [IndexSearcher](xref:Lucene.Net.Search.IndexSearcher) -and pass the query to its [Search](xref:Lucene.Net.Search.IndexSearcher#methods) -method. - -Some simple examples of code which does this are: - -* [IndexFiles.java](../demo/src-html/org/apache/lucene/demo/IndexFiles.html) creates an -index for all the files contained in a directory. - -* [SearchFiles.java](../demo/src-html/org/apache/lucene/demo/SearchFiles.html) prompts for -queries and searches an index. - + // Store the index in memory: + Directory directory = new RAMDirectory(); + // To store an index on disk, use this instead: + //Directory directory = FSDirectory.open("/tmp/testindex"); + IndexWriterConfig config = new IndexWriterConfig(Version.LUCENE_CURRENT, analyzer); + IndexWriter iwriter = new IndexWriter(directory, config); + Document doc = new Document(); + String text = "This is the text to be indexed."; + doc.add(new Field("fieldname", text, TextField.TYPE_STORED)); + iwriter.addDocument(doc); + iwriter.close(); + + // Now search the index: + DirectoryReader ireader = DirectoryReader.open(directory); + IndexSearcher isearcher = new IndexSearcher(ireader); + // Parse a simple query that searches for "text": + QueryParser parser = new QueryParser(Version.LUCENE_CURRENT, "fieldname", analyzer); + Query query = parser.parse("text"); + ScoreDoc[] hits = isearcher.search(query, null, 1000).scoreDocs; + assertEquals(1, hits.length); + // Iterate through the results: + for (int i = 0; i < hits.length;="" i++)="" {="" document="" hitdoc="isearcher.doc(hits[i].doc);" assertequals("this="" is="" the="" text="" to="" be="" indexed.",="" hitdoc.get("fieldname"));="" }="" ireader.close();=""> + +The Lucene API is divided into several packages: + +* __<xref:Lucene.Net.Analysis>__ +defines an abstract [Analyzer](xref:Lucene.Net.Analysis.Analyzer) +API for converting text from a {@link java.io.Reader} +into a [TokenStream](xref:Lucene.Net.Analysis.TokenStream), +an enumeration of token [Attribute](xref:Lucene.Net.Util.Attribute)s. +A TokenStream can be composed by applying [TokenFilter](xref:Lucene.Net.Analysis.TokenFilter)s +to the output of a [Tokenizer](xref:Lucene.Net.Analysis.Tokenizer). +Tokenizers and TokenFilters are strung together and applied with an [Analyzer](xref:Lucene.Net.Analysis.Analyzer). +[analyzers-common](../analyzers-common/overview-summary.html) provides a number of Analyzer implementations, including +[StopAnalyzer](../analyzers-common/org/apache/lucene/analysis/core/StopAnalyzer.html) +and the grammar-based [StandardAnalyzer](../analyzers-common/org/apache/lucene/analysis/standard/StandardAnalyzer.html). + + +* __<xref:Lucene.Net.Codecs>__ +provides an abstraction over the encoding and decoding of the inverted index structure, +as well as different implementations that can be chosen depending upon application needs. + + +* __<xref:Lucene.Net.Documents>__ +provides a simple [Document](xref:Lucene.Net.Documents.Document) +class. A Document is simply a set of named [Field](xref:Lucene.Net.Documents.Field)s, +whose values may be strings or instances of {@link java.io.Reader}. + + +* __<xref:Lucene.Net.Index>__ +provides two primary classes: [IndexWriter](xref:Lucene.Net.Index.IndexWriter), +which creates and adds documents to indices; and <xref:Lucene.Net.Index.IndexReader>, +which accesses the data in the index. + + +* __<xref:Lucene.Net.Search>__ +provides data structures to represent queries (ie [TermQuery](xref:Lucene.Net.Search.TermQuery) +for individual words, [PhraseQuery](xref:Lucene.Net.Search.PhraseQuery) +for phrases, and [BooleanQuery](xref:Lucene.Net.Search.BooleanQuery) +for boolean combinations of queries) and the [IndexSearcher](xref:Lucene.Net.Search.IndexSearcher) +which turns queries into [TopDocs](xref:Lucene.Net.Search.TopDocs). +A number of [QueryParser](../queryparser/overview-summary.html)s are provided for producing +query structures from strings or xml. + + +* __<xref:Lucene.Net.Store>__ +defines an abstract class for storing persistent data, the [Directory](xref:Lucene.Net.Store.Directory), +which is a collection of named files written by an [IndexOutput](xref:Lucene.Net.Store.IndexOutput) +and read by an [IndexInput](xref:Lucene.Net.Store.IndexInput). +Multiple implementations are provided, including [FSDirectory](xref:Lucene.Net.Store.FSDirectory), +which uses a file system directory to store files, and [RAMDirectory](xref:Lucene.Net.Store.RAMDirectory) +which implements files as memory-resident data structures. + + +* __<xref:Lucene.Net.Util>__ +contains a few handy data structures and util classes, ie [OpenBitSet](xref:Lucene.Net.Util.OpenBitSet) +and [PriorityQueue](xref:Lucene.Net.Util.PriorityQueue). + +To use Lucene, an application should: + +1. Create [Document](xref:Lucene.Net.Documents.Document)s by +adding +[Field](xref:Lucene.Net.Documents.Field)s; + + +2. Create an [IndexWriter](xref:Lucene.Net.Index.IndexWriter) +and add documents to it with [AddDocument](xref:Lucene.Net.Index.IndexWriter#methods); + + +3. Call [QueryParser.parse()](../queryparser/org/apache/lucene/queryparser/classic/QueryParserBase.html#parse(java.lang.String)) +to build a query from a string; and + + +4. Create an [IndexSearcher](xref:Lucene.Net.Search.IndexSearcher) +and pass the query to its [Search](xref:Lucene.Net.Search.IndexSearcher#methods) +method. + +Some simple examples of code which does this are: + +* [IndexFiles.java](../demo/src-html/org/apache/lucene/demo/IndexFiles.html) creates an +index for all the files contained in a directory. + + +* [SearchFiles.java](../demo/src-html/org/apache/lucene/demo/SearchFiles.html) prompts for +queries and searches an index. + diff --git a/websites/apidocs/LuceneTemplate/partials/breadcrumb.tmpl.partial b/websites/apidocs/LuceneTemplate/partials/breadcrumb.tmpl.partial new file mode 100644 index 0000000..8320e92 --- /dev/null +++ b/websites/apidocs/LuceneTemplate/partials/breadcrumb.tmpl.partial @@ -0,0 +1,16 @@ +{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} + +<div class="subnav navbar navbar-default"> + <div class="container hide-when-search"> + <ul class="level0 breadcrumb"> + <li> + <a href="/">API</a> + <span id="breadcrumb"> + <ul class="breadcrumb"> + <li>{{_tocTitle}}</li> + </ul> + </span> + </li> + </ul> + </div> +</div> diff --git a/websites/apidocs/LuceneTemplateAssets/styles/main.css b/websites/apidocs/LuceneTemplateAssets/styles/main.css index 93ed9b5..056bc0e 100644 --- a/websites/apidocs/LuceneTemplateAssets/styles/main.css +++ b/websites/apidocs/LuceneTemplateAssets/styles/main.css @@ -91,3 +91,13 @@ body .toc { .sidefilter { background-color: rgb(247, 247, 247); } + +.level1.breadcrumb { + display: inline; +} + +.level0.breadcrumb .level1.breadcrumb > li:before { + content: "\00a0/"; + padding: 0 5px; + color: #ccc; +} \ No newline at end of file diff --git a/websites/apidocs/docfx.core.json b/websites/apidocs/docfx.core.json index f4a6356..01f42a3 100644 --- a/websites/apidocs/docfx.core.json +++ b/websites/apidocs/docfx.core.json @@ -33,17 +33,13 @@ "**.md" ], "src": "obj/docfx/api/core" - }, - { - "files": [ - "toc/core/toc.yml" - ] - }, + }, { "files": [ - "toc.yml" + "toc.yml", + "core/toc.yml" ], - "src": "toc/subsite" + "src": "toc" } ], "overwrite": [ diff --git a/websites/apidocs/docfx.global.json b/websites/apidocs/docfx.global.json new file mode 100644 index 0000000..de7bcda --- /dev/null +++ b/websites/apidocs/docfx.global.json @@ -0,0 +1,14 @@ +{ + "_appTitle": "Apache Lucene.NET 4.8.0-beta00008 Documentation", + "_disableContribution": false, + "_appFaviconPath": "logo/favicon.ico", + "_enableSearch": true, + "_appLogoPath": "logo/lucene-net-color.png", + "_appFooter": "Copyright © 2020 Licensed to the Apache Software Foundation (ASF)", + "_gitContribute": { + "repo": "https://github.com/apache/lucenenet";, + "branch": "docs/4.8.0-beta00008", + "apiSpecFolder": "websites/apidocs/apiSpec" + }, + "_gitSource": "https://github.com/apache/lucenenet.git"; +} diff --git a/websites/apidocs/docfx.global.subsite.json b/websites/apidocs/docfx.global.subsite.json new file mode 100644 index 0000000..e169f9e --- /dev/null +++ b/websites/apidocs/docfx.global.subsite.json @@ -0,0 +1,3 @@ +{ + "_rel": "/" +} diff --git a/websites/apidocs/docfx.site.json b/websites/apidocs/docfx.site.json index 631f909..347402f 100644 --- a/websites/apidocs/docfx.site.json +++ b/websites/apidocs/docfx.site.json @@ -19,6 +19,9 @@ "src": "../../branding" } ], + "xref": [ + "_site/api/core/xrefmap.yml" + ], "dest": "_site", "globalMetadataFiles": ["docfx.global.json"], "template": [ diff --git a/websites/apidocs/docs.ps1 b/websites/apidocs/docs.ps1 index a5c613e..886661b 100644 --- a/websites/apidocs/docs.ps1 +++ b/websites/apidocs/docs.ps1 @@ -30,7 +30,10 @@ param ( # LogLevel can be: Diagnostic, Verbose, Info, Warning, Error [Parameter(Mandatory = $false)] [string] - $LogLevel = 'Warning' + $LogLevel = 'Warning', + [Parameter(Mandatory = $false)] + [string] + $BaseUrl = 'http://localhost:8080' ) [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 @@ -107,6 +110,11 @@ $PluginsFolder = (Join-Path -Path $ApiDocsFolder "lucenetemplate\plugins") New-Item $PluginsFolder -type directory -force & $msbuild $pluginSln /target:LuceneDocsPlugins "/p:OutDir=$PluginsFolder" +# Set the DocFx MSBuild path manually, for some reason it borks if using the default +# [Environment]::SetEnvironmentVariable("MSBUILD_EXE_PATH", $msbuild) +# [Environment]::SetEnvironmentVariable("MSBUILD_EXE_PATH", "C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\MSBuild\Current\Bin\MSBuild.exe") +# [Environment]::SetEnvironmentVariable("VisualStudioVersion", "15.0") + # update the docjx.global.json file based $DocFxGlobalJson = Join-Path -Path $ApiDocsFolder "docfx.global.json" $DocFxJsonContent = Get-Content $DocFxGlobalJson | ConvertFrom-Json @@ -116,8 +124,8 @@ $DocFxJsonContent._gitContribute.branch = "docs/$LuceneNetVersion" $DocFxJsonContent | ConvertTo-Json -depth 100 | Set-Content $DocFxGlobalJson $DocFxJsonMeta = @( - "docfx.core.json", - "docfx.test-framework.json" + "docfx.core.json" + #"docfx.test-framework.json" ) $DocFxJsonSite = Join-Path -Path $ApiDocsFolder "docfx.site.json" @@ -155,6 +163,21 @@ if ($?) { else { & $DocFxExe build $projFile --log "$DocFxLog" --loglevel $LogLevel --debug } + + # Add the baseUrl to the output xrefmap, see https://github.com/dotnet/docfx/issues/2346#issuecomment-356054027 + $projFileJson = Get-Content $projFile | ConvertFrom-Json + $projBuildDest = $projFileJson.build.dest + $buildOutputFolder = Join-Path -Path ((Get-Item $projFile).DirectoryName) $projBuildDest + $xrefFile = Join-Path $buildOutputFolder "xrefmap.yml" + $xrefMap = Get-Content $xrefFile -Raw + $xrefMap = $xrefMap.Replace("### YamlMime:XRefMap", "").Trim() + $projBaseUrl = $BaseUrl + $projBuildDest.Substring(5, $projBuildDest.Length - 5) # trim the _site part of the string + $xrefMap = "### YamlMime:XRefMap" + [Environment]::NewLine + "baseUrl: " + $projBaseUrl + "/" + [Environment]::NewLine + $xrefMap + Set-Content -Path $xrefFile -Value $xrefMap + + # TODO: Figure out why this doesn't work as expected, the absolute path isn't quite right. + # // baseUrl: https://xxxx.azurewebsites.net/, https://github.com/dotnet/docfx/issues/2346#issuecomment-356054027 + # TODO: We want to make the breadcrumb like microsofts so that the first segment of it is the home page. } } diff --git a/websites/apidocs/toc.yml b/websites/apidocs/toc.yml index b111255..d8c4edd 100644 --- a/websites/apidocs/toc.yml +++ b/websites/apidocs/toc.yml @@ -1,5 +1,5 @@ - name: Lucene.Net API - href: / + topicHref: / - name: Lucene.Net CLI href: ../../src/dotnet/tools/lucene-cli/docs/ topicHref: ../../src/dotnet/tools/lucene-cli/docs/index.md diff --git a/websites/apidocs/toc/core/toc.yml b/websites/apidocs/toc/core/toc.yml index 305d3be..c62eed1 100644 --- a/websites/apidocs/toc/core/toc.yml +++ b/websites/apidocs/toc/core/toc.yml @@ -1,3 +1,3 @@ -- name: Lucene.Net - href: ../../obj/docfx/api/core/toc.yml - topicUid: Lucene.Net \ No newline at end of file +- name: Core + topicUid: Lucene.Net + href: ../../obj/docfx/api/core/toc.yml \ No newline at end of file diff --git a/websites/apidocs/toc/subsite/toc.yml b/websites/apidocs/toc/subsite/toc.yml deleted file mode 100644 index 033099d..0000000 --- a/websites/apidocs/toc/subsite/toc.yml +++ /dev/null @@ -1,6 +0,0 @@ -- name: Lucene.Net API - href: / -- name: Lucene.Net CLI - href: /cli/index.html -- name: Lucene.Net Website - href: https://lucenenet.apache.org/ \ No newline at end of file diff --git a/websites/apidocs/toc/toc.yml b/websites/apidocs/toc/toc.yml new file mode 100644 index 0000000..cc7c562 --- /dev/null +++ b/websites/apidocs/toc/toc.yml @@ -0,0 +1,2 @@ +- name: Lucene.Net API + topicHref: / \ No newline at end of file
