Merge: nitdoc: full rewrite
authorJean Privat <jean@pryen.org>
Wed, 20 Jun 2018 18:59:16 +0000 (14:59 -0400)
committerJean Privat <jean@pryen.org>
Wed, 20 Jun 2018 18:59:16 +0000 (14:59 -0400)
commit74398ebe85ee2337efa986205531b3ca696c8543
tree72eaa8679b88265891d0866d735c210d1b1ac046
parentad624f2d5401e900b3b8cf574cdacd7f51ef6915
parent18fa4c2e9c6eb551f9f90fda368edad57752e8cc
Merge: nitdoc: full rewrite

This PR introduces a new version of Nitdoc based on DocCommands.
The main objective is to unify the display with `nitweb`.
Beside a cleaner implementation and the removal of a lot of code here a quick presentation of the new tool.

### Replace Overview page by Nit Catalog

Avoiding the clutter of the old overview page.

![home](https://user-images.githubusercontent.com/583144/40859182-df1db392-65ae-11e8-82d6-8abd1708722e.png)

This closes #1516

### New packages pages

Package READMEs are now rendered with support of `[[doc commands]]`

![screenshot from 2018-06-01 15 19 10](https://user-images.githubusercontent.com/583144/40859246-263b4a14-65af-11e8-9fe8-4806fedc4a2a.png)

### Simplified modules pages

The modules pages offer a simplified view of its content with introduced and redefined classes:

![screenshot from 2018-06-01 15 23 28](https://user-images.githubusercontent.com/583144/40859466-ed481434-65af-11e8-8c06-88d8b50b17e2.png)

### Module code view

The source code of a module can be viewed directly in the documentation:

![screenshot from 2018-06-01 15 25 12](https://user-images.githubusercontent.com/583144/40860212-9bca9192-65b2-11e8-9115-a623a3d9f026.png)

Entities in the source code can be clicked to access the related documentation page.
This closes #953.

### Class & property linearization

In the new nitdoc, I totally removed the concept of definition pages. Thus no more page for a MClassDef or a MPropDef.

Instead we present the linearization of a MClass or MProperty like in nitweb.

![screenshot from 2018-06-01 15 27 53](https://user-images.githubusercontent.com/583144/40859654-89aa4cca-65b0-11e8-9e2a-0f710a9186ea.png)

There is now a simple rule for where a click on a class or property will land:
* If the user clicks on an introduction, the target page is the documentation of the class or property (the intro def)
* If the user clicks on a redefinition, the target is the definition card in the linearization list.

Beside in the linearization lists, there is only two places where you can find a link to a redefinition:
* in the **Redefined classes** of a module page (tab #doc)
* in the **Redefined properties** of a class page (tab #doc)

Here also, the code is linked to the documentation.

I applied heuristics that disable the linearization lists for:
* `Sys`
* `Object::SELF`
* `Object::init`
* `Object::to_s`

This closes #1563.

### Better quicksearch results

In order to close #361, I added an heuristic to place the packages and modules on top of the list depending on the query.

If the query has a better matches with properties, they will be presented in top, here an example for the query `pop`:

![screenshot from 2018-06-01 15 36 44](https://user-images.githubusercontent.com/583144/40859970-9a7a4ce8-65b1-11e8-9a84-c6fc83886e96.png)

The `pop` first matches `pop` and `popup` then we presents the packages and modules `popcorn`.

For the query `popc`:

![screenshot from 2018-06-01 15 37 57](https://user-images.githubusercontent.com/583144/40860045-e0eea2dc-65b1-11e8-90d1-5f233ce7d204.png)

We directly show the matches for the packages and modules (same behavior than before).

### Redesign

The new design (imported from nitweb) add a lot of free spaces for future PR like example suggestions, doc generation, call graphs etc.

We can benefit from the tabbed view to add new content (like in nitweb with the license et contrib rules for examples).
We can also use the space under the documentation to introduce examples and other things.

### Regressions

The only regression is the disappearance of concerns sections. I'm working on it with new doc commands.

Final note, it also closes #962.

Pull-Request: #2707