Page MenuHomePhabricator

Add support for DocFx to generate the C# API docs
Closed, ResolvedPublic

Description

As requested by @myoungwoon in D7126#123769, study the possibility to use DocFx to generate the C# API docs as it is being done for Tizen.

The output of this task should be a list of pros and cons to further discuss the move.

Remaining tasks:

  • Filter out unwanted API (legacy, ...)
  • Check that cross referencing works (links to other APIs, methods, ...)
  • Display only useful info (remove long inheritance trees, protected methods, ...)
  • Use the site's theme
  • Add tutorials and programming guides
segfaultxavi triaged this task as Normal priority.
segfaultxavi added a comment.EditedOct 5 2018, 4:29 AM

Installation on Linux is trivial, just download docfx.zip, unzip wherever you want (I used ~/docfx/) and add this little script (call it docfx and give it execution permission) somewhere in your path:

#!/bin/bash
mono ~/docfx/docfx.exe $@

Then, in your EFL checkout:

docfx init

Answer all questions (I used the default folder docfx_project, set the source directory to ../src and the files Glob pattern to lib/efl_mono/libefl_mono.dll).
To be sure, after running docfx init, the top of your docfx_project/docfx.json file should be similar to this:

{
  "metadata": [
    {
      "src": [
        {
          "src": "../src",
          "files": [
            "lib/efl_mono/libefl_mono.dll"
          ]
        }
      ],

Then you run:

docfx docfx_project/docfx.json

And, after 20 minutes of process and consuming about 2GB of RAM, it uses up 600MB of hard drive. Most of this disk space is used for caches, the actual HTML folder (_site by default) is about 90MB. A second run after modifying a single cs file took "only" 5 minutes.
If you then open _site/api/index.html with a browser, you can see our classes in all their glory. It's got the usual Collapsible Site Navigation left side bar (including a search box), the page TOC right side bar (with auto-highlight as you scroll), inheritance graphs, internal links, etc.

Screenshot attached for your convenience.

Next step is to start customizing it to see if it fits all our needs.

segfaultxavi updated the task description. (Show Details)Nov 6 2018, 4:25 AM
segfaultxavi updated the task description. (Show Details)Nov 6 2018, 4:52 AM
segfaultxavi updated the task description. (Show Details)Nov 6 2018, 7:18 AM
segfaultxavi updated the task description. (Show Details)Nov 8 2018, 4:46 AM

A branch has been created with the tests: devs/xartigas/docfx-support
Some notes about the tasks:

  • Filter out unwanted API (legacy, ...)
    • Easy enough using the filter keyword as shown in the testing branch.
  • Check that cross referencing works (links to other APIs, methods, ...)
    • Automatic method linking is pending on T7453
  • Add tutorials and programming guides
    • Section headers in DokuWiki create anchors named #The_Space_Box whereas in DocFx they are named #the-spacer-box. All section links in md files will need to be changed.
    • Links to other documents do not need to change much if we use the same folder structure.
    • DokuWiki headers need to be removed from every md file.
segfaultxavi moved this task from Backlog to In progress on the efl: docs board.Dec 5 2018, 9:38 AM
segfaultxavi renamed this task from Study usage of DocFx to generate the C# API docs to Add support for DocFx to generate the C# API docs.Dec 14 2018, 2:22 AM
segfaultxavi raised the priority of this task from Normal to High.
segfaultxavi updated the task description. (Show Details)
segfaultxavi closed this task as Resolved.Jan 7 2019, 8:16 AM

Closed by D7502. The remaining issues can be tracked from new tasks:

  • Display only useful info (remove long inheritance trees, protected methods, ...)
  • Use the site's theme
segfaultxavi moved this task from In progress to Done on the efl: docs board.Thu, Mar 21, 8:30 AM