lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] [lucenenet] Shazwazza opened a new pull request #304: Docs overhaul and beta00009 docs release
Date Tue, 30 Jun 2020 23:59:46 GMT

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:
users@infra.apache.org



Mime
View raw message