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 Thu, 14 Sep 2017 07:26:06 GMT
Github user NightOwl888 commented on the issue:

    https://github.com/apache/lucenenet/pull/206
  
    @Shazwazza 
    
    Looking good.
    
    I like the drill down packages, although what I had in mind was a bit simpler than that
- basically I was thinking to link over to the page and autofill the search box so it would
filter for the namespace. Then the user would have a way to remove the filter just by deleting
the text. But don't change it on my account, as long is it is functional its all good.
    
    ### Release
    
    I am getting really close to finishing up the release, and it is looking like we will
be able to start the release vote as early as next week. The only thing left on the list above
is to package up the the CLI utility and the API docs. There are a few failing tests I am
tracking down and a few other tasks to do, but nothing very time consuming. I think the most
time consuming task will be manual cleanup of the overview/package documents.
    
    If you have a chance this weekend would be ideal to try to get this to the point where
we can do our first docs release. I don't expect it to be perfect and there can be additional
pull requests after this one, but lets just try to make it functional.
    
    Do note for a release, we need to add an Apache license header to every file (source,
config, project, and documentation). There is a tool called [RAT](https://creadur.apache.org/rat/)
that can automate that step. Take care not to do it on the test files, as we had an issue
on the last release after changing some of them.
    
    ### JavaDoc to Markdown Conversion Tool/Package Docs
    
    I have committed the [JavaDocToMarkdownConverter tool](https://github.com/apache/lucenenet/tree/master/src/dotnet/tools/JavaDocToMarkdownConverter)
and have also done a preliminary conversion (with no manual changes) so you can work out how
to consume the documents. There are 244 markdown docs, but I am not sure we need the one liners.
If you can't work out what to do with them, perhaps we should just setup the generator to
automatically delete documents that are less than 900 bytes, which would eliminate them if
they don't have any useful content.
    
    I ended up changing the names from readme.md back to overview.md and package.md because
in some places they would collide due to being written to the same directory.
    
    ### Namespace Links
    
    I still haven't worked out what to do about namespace links. Hopefully once you consume
them with DocFx, you can work out and provide me with a better idea how to convert them -
it would be nice to automate that part as much as possible before doing the manual cleanup
work.
    
    ### Code Links
    
    I followed the approach in the links you sent using `[link text](xref:uid)`. Let me know
if that works, as I have not tested with DocFx.
    
    > 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
    
    For that, you would need special permissions (I think Prescott would be the one to ask
about that). But the info on the WIKI is so far out of date I am not sure it is much use at
this point. What specifically do you want to do with it?
    
    I tried to copy and paste it here, but apparently the text is formatted using JavaScript
and when copied it just comes out plain text with no formatting - not even breaks between
paragraphs.
    
    ### New .csproj Format
    
    Do note I have also upgraded us to the new .csproj format (and moved some projects to
a new dotnet folder). I noticed you are referencing some of these files, and I hope the new
format isn't a blocker for DocFx. Basically, they no longer contain any of the file references
- all files are loaded by default and they are manually excluded them when you don't want
them.
    
    The solution will also only load in Visual Studio 2017 (15.3 or higher).
    
    ### Build
    
    I thought I saw a comment above about what part of the build this is going in, but I don't
see it now. Basically, we will be adding this to the Lucene.Net Release task in TeamCity (https://teamcity.jetbrains.com/project.html?projectId=LuceneNet_PortableBuilds&tab=projectOverview).

    
    I think the first time out we can just do the documentation build and deployment manually,
which will give me some idea how to setup the build. But one thing I do know for sure is that
we will need to add a parameter to the powershell build script to pass in the Git tag that
corresponds to the current build, and this value should replace `{tag}` in the repo links.
Keep in mind, we may need to do this from the regular API docs as well.
    
    ### .gitignore
    
    Still having an issue. You have ignored the `apidocs` folder, but there is another folder
that gets generated in the root directory named `api` that is not ignored.
    
    ### Lucene.Net.Cli
    
    This should be excluded from the API docs since it is not consumable. But we will want
to include the usage documentation under `src\dotnet\tools\lucene-cli\docs\`.
    
    ### Lucene.Net.ICU
    
    This is kind of an oddball package and is probably going to be tough to do the documentation
for. Basically, the code files were left in their original locations, but they are linked
to and compiled into this project from several other projects. If this turns out to be too
challenging to create the documentation, don't worry about it for this release - it is the
most buggy part of Lucene.Net for the time being, anyway.


---

Mime
View raw message