Github user Shazwazza commented on the issue:
https://github.com/apache/lucenenet/pull/206
Hi all,
Here's some feedback on many of the above questions/comments:
I've pushed some updates to this PR which:
* Fixed up a couple of cref's
* Updated to use latest docfx v2.17.x release (be sure to delete the /tools
folder) to get the latest version when running the ps1 script. Unfortunatey
upgrading to the very latest docfx 2.19.2 causes build errors. I also checked
that 2.18.x also causes these build errors. I'm putting together a bug report
for this now. I has to do with some YAML parsing errors and things like "quoted
scalar" and "orphaned high surrogate" which sound fun ;)
* Adds some comments to the ps1 script about where other docs live and
potentially somehow scraping/automating fetching these docs
* Update the home page of the docs to mimic
https://lucene.apache.org/core/4_8_0/, I've just copied the HTML, then removed
the html/body tags and replaced the header tags with Markdown header tags so
they are parsed correctly by DocFx to create the side menu. The links
throughout this document will need to be updated since they still point to the
lucene.apache.org links. I've done this to show that HTML markup works happily
side by side and inline with Markdown with DocFx which will probably make it
easier to scrape docs.
* Adds a landing page in the API Docs section which is a copy of this page:
https://github.com/apache/lucene-solr/blob/branch_4x/lucene/core/src/java/overview.html
(links would need to be fixed), this file is committed to /api/index.md
* Adds example docs and table of contents: /api/search/highlight which
includes the docs taken from the package.html files (i.e.
https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/highlighter/src/java/org/apache/lucene/search/highlight/package.html)
* Updated the header menu to point to custom documentation articles and
also the API docs
I cannot figure out why docfx is complaining about System cref's such as
`Invalid cref value "T:IDictionary{string, string}"`, i think it has to do with
a missing config `externalReference` which is now obsoleted so hoping that the
newer docfx version fixes this once i get it building.
If you wish to test this setup without waiting for the entire metadata for
all classes to be created, you can update the /docfx.json file
metadata/src/files section from `"**.csproj"` to `"**/Lucene.Net.csproj"`
(which will just generate the API docs for that particular project), or just
clear that out entirely if you just want to build the non-api docs for testing.
Currently DocFx does not support the namespace style docuementation that
Sandcastle used to support, there's an open issue for that here:
https://github.com/dotnet/docfx/issues/952 So for namespace style documentation
such as
https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/highlighter/src/java/org/apache/lucene/search/highlight/package.html
we would currently have to host these as documentation articles. Currently
I've put documentation articles in the /docs folder but it's possible to have
any number of different articles folders if required.
As for changing how the namespaces are shown on the left hand side and
ordering by more important ones, this could be achieved by modifying the
generated /api/toc.yml file after it is built. This file is autogenerated by
docfx when it's building the API docs. As far as I can tell one way to do this
would be with a custom Post Processor:
https://dotnet.github.io/docfx/tutorial/howto_add_a_customized_post_processor.html
but OOTB I don't think this is possible with standard configuration.
I'm not really sure what we can do about the .NET Standard vs .NET
Framework, there is some mention of this in this issue:
https://github.com/dotnet/docfx/issues/1518 which apparently is fixed in this
PR https://github.com/dotnet/docfx/pull/1549 . I will just need to figure out
exactly what all this means and what the options are.
For token replacement, i think this could also be achieved with a Post
Processor in one way or another
https://dotnet.github.io/docfx/tutorial/howto_add_a_customized_post_processor.html,
though i did see this feature in later release notes:
https://github.com/dotnet/docfx/issues/1737
There's quite a lot of docs on docfx here
http://dotnet.github.io/docfx/tutorial/docfx_getting_started.html
Hope this answers a few of your questions. I'll keep researching into the
new docfx versions, what support it has and why we can't use it currently.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
