Shazwazza opened a new pull request #304: URL: https://github.com/apache/lucenenet/pull/304
There are quite a lot of changes here. Just creating a PR for completeness with notes. The main issue with docs before was that due to the nature of how the Lucene project is structured (this comes from Java), there are quite a few overlapping namespaces between projects and the way docfx works is that each namespace, class, etc... gets assigned its own ID (UID) which is based on how Roslyn queries those types so it's not very flexible to try to change the UID results. Previously we had a single docfx api docs site that would build the metadata for all projects and then build a single site. This seemed to work however you would quickly notice that the links weren't working which is due to overlapping/colliding UIDs (xrefs). The new docs format means we create a docfx 'site' per Lucene package (i.e. Core, Common Analysis, Facets, etc... ). This is actually the way that the Lucene api docs are structured too and how Microsoft's own docs are structured (more or less). Now each package site is build separately from each other which means no colliding UIDs and links work correctly. We then build the containing site and pass in all exported xref docs from each package so that the wrapping site can auto-link through to the package sites. This is still a little buggy because there is of course still colliding xrefs but we can fix this up more easily. See https://github.com/apache/lucenenet/issues/300 * docs.ps1 has been updated with better script parameters allowing more granular control over the build * separating each package into it's own docfx files * separating the templates out so that we are not duplicating the need for assets in each package site * adds separate toc files for each package site to provide more granular control * uses JS extensions in templates to ensure that the Git source repo linked to when using the "View Source" button is always the main lucenenet git repo, else it can show up as your own local repository because this is controlled purely by git commands (not configurable in docfx) ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
