Github user Shazwazza commented on the issue:
https://github.com/apache/lucenenet/pull/206
Some comments inline:
> The api folder is not currently in .gitignore, so the .yml documents all
appear as uncommitted files.
I have this in the .gitignore `apidocs/api/*.yml` which seems to work for
me, maybe that was added to this PR after you commented, not sure.
> Code links
DocFx supports the idea of "UDI" which is the page identifier. AFAIK you
can use these to cross link between pages or docs during docfx's compile time
linking. So we 'should' be able to use that to link to any API or page from
another page without needing to know exactly where it lives ... so long as the
UDI doesn't change. A class's UDI is it's fully qualified name and a page's can
be defined by us. Here's the docfx docs on this type of thing
*
https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html#different-syntax-of-cross-reference
*
https://dotnet.github.io/docfx/spec/metadata_dotnet_spec.html#21-unique-identifiers
So i think this should 'just work' if we use/create UDIs for documents we
want to link to and code docs will already have a UDI.
We can create custom Markdown parsers for whatever syntax you choose (like
I did for the `@lucene.experimental` tokens) so I think if you want to stay
with the `<see>` and using a UDI reference we might be able to parse these into
whatever docfx wants before it does it's linking (i guess it depends on at what
stage in the compiling that is). Otherwise since we have full access to the
docfx APIs when doing this custom parsing I assume I can just generate the
correct link for the UDI.
> Is there such a thing as a filter that can be applied to the TOC so that
only the part from a single .NET assembly appears at a time
Not as far as I know OOTB however, the same thing could be achieved by post
processing and generating the filtered TOC yml files for each package ->
namespace . I might post this question on the docfx GH page and see if anyone
has done this before.
... i might give this a try and see if i can make a POC
> Unfortunately, the format of the WIKI is not markdown. Here is the
documentation for the Confluence WIKI markup format. Maybe a converter for this
format to markdown exists, though...?
There seems to be a few converters out there but not sure if they work
specifically for Confluence WIKI format. I feel pretty dumb asking this but how
the heck do you see the WIKI format source for this?
https://cwiki.apache.org/confluence/display/LUCENENET/Lucene.Net
I've pushed an update to the build to use latest docfx, you'll want to
clear out your apidocs/tools folder before running the build again.
I'll report back (hopefully soon-ish) with what i find about the TOC
---
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.
---
