Skip to content

Enormous documentation overhaul

Mateusz Brawański requested to merge github/fork/uwx/patch-104 into master

Created by: uwx

Summary

This is a very large update to the documentation site, with the objective of turning it from a crapshoot into an useful, browsable and searchable resource, hopefully reducing the amount of technical support questions that are easy to answer and helping everyone who doesn't know the library top to bottom as well.

A live test of this PR is available at: https://uwx.github.io/DSharpPlusDocsTest/index.html

It's important to mention that, because of how the file structure in the documentation is, there are a few missing images in the live test. These will not show up in production.

Details

I have added support for displaying "equivalent names" for some members. These can be defined in the remarks section of the xmldocs for a member as follows:

/// <remarks>[alias="AliasName"]</remarks>

You can also chain multiple aliases:

/// <remarks>[alias="Alias1Name"][alias="Alias2Name"]</remarks>

You can still use the remarks section normally and even have aliases at the same time, the parser will simply remove the alias definitions and excess space from the remarks section in the documentation:

/// <remarks>
/// This method does weird stuff.
/// [alias="Alias1Name"][alias="Alias2Name"]
/// </remarks>

--

I have enabled full-text search and indexing, which is a DocFX feature that was previously not enabled. However, the built-in DocFX search functionality is very limited and has some (in my opinion) ugly results. To complement the built-in search, I added a custom indexer that will add members of types to the search index (standard DocFX will only index full types and custom articles). Also, you can search type members by their equivalent names!

In addition to the indexer, I modified the existing search system to show actual useful information besides just a title and a bunch of garbled text that is used by the indexer. Specifically, it now shows the summary as well as the signature (if applicable).

There were also other minor changes to the CSS for readability and organization's sake, but they only affect the search results pane.

--

As a tiny bonus, I updated the copyright date at the footer.

Screenshots

equivalent names screenshot 1 equivalent names screenshot 2 full text search screenshot 1 full text search screenshot 2 full text search screenshot 3 updated copyright screenshot

Changes proposed

  • Added "equivalent names" system to the documentation, by hooking the transformation step in the ManagedReference template script, and adding the necessary HTML in the customMREFContent template
  • Enabled full-text search and indexing
    • Added a placeholder when doing the first time full-text search, so the user does not think something is broken or that there were no results
  • Added a custom indexer (in the form of a DocFX post processing plugin) for full-text search that indexes a type's members (adding functionality onto what the built-in indexer already does)
    • This also adds item summary and member signature (if applicable) to the search results, which required changes in the search code
    • This also adds the CsQuery license to the plugins folder as it is used in the indexer
  • Minor CSS changes for prettier search results
  • Updated copyright year in the footer of the documentation

Notes

This PR is thoroughly tested. I mean, that's kind of the only way for me to see what my code is doing. You get the idea.

Merge request reports