lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Shazwazza <...@git.apache.org>
Subject [GitHub] lucenenet issue #206: API Doc site generator using DocFx script
Date Thu, 24 Aug 2017 09:05:32 GMT
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message