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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

Reply via email to