lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From NightOwl888 <...@git.apache.org>
Subject [GitHub] lucenenet issue #206: API Doc site generator using DocFx script
Date Wed, 09 Aug 2017 06:38:10 GMT
Github user NightOwl888 commented on the issue:

    https://github.com/apache/lucenenet/pull/206
  
    During the building of a tool to get the `.html` pages converted, I can break the types
of links we have into 3 categories:
    
    1. Code links
    2. Repo links
    3. Namespace links
    
    I am using a library Html2Markdown to convert the text into markdown docs, and naming
them all readme.md so they show up by default on GitHub when viewing the folder.
    
    ### Code links
    
    For the first category, I have (for the time being at least) used a similar method as
in the C# doc comments.
    
    ```
    <see cref="Lucene.Net.Search.Query">Query</see>
    ```
    The primary difference being that it accepts an optional inner text, which is meant to
be the link text. If these are hard-coded to the relative path of the code element doc, I
think it might be difficult to manage if we end up moving stuff around later.
    
    Without the link text, the `see` element is simply closed.
    
    ```
    <see cref="Lucene.Net.Search.Query"/>
    ```
    
    ### Repo links
    
    This one is a bit tricky as well:
    
    ```
    [IndexFiles](https://github.com/apache/lucenenet/blob/{tag}/src/Lucene.Net.Demo/IndexFiles.cs)
    ```
    
    We need to accept the tag as a powershell parameter from the release process when generating
these docs, so when we change versions this API doc is pointing to the version it applies
to.
    
    ### Namespace links
    
    This one I haven't worked out yet. As long as we can put a TOC that is filtered for the
current namespace on the left side, we should be able to use the approach you mentioned with
the WIKI page to build namespace documentation. It would be ideal if these documents were
the `index.html` for the namespace so we could just chop off the current page from relative
links to get to the "current" namespace.
    
    ------------------------
    
    I am curious if you think it will be too difficult to convert those `<see>` elements
into code links, or if we should just generate them as hard links to the API docs now?



---
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