Page MenuHomePhabricator

doc: Add support for DocFX (C# doc generator)
ClosedPublic

Authored by segfaultxavi on Dec 21 2018, 7:38 AM.

Details

Summary

Usage instructions in the README file.

Test Plan

Follow the README to produce the documentation pages.
Point your browser to docfx/_site/index.html to see the results.

Diff Detail

Repository
rEFL core/efl
Branch
devs/xartigas/docfx-support
Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 8693
Build 7690: arc lint + arc unit
segfaultxavi created this revision.Dec 21 2018, 7:38 AM
segfaultxavi requested review of this revision.Dec 21 2018, 7:38 AM

Added the "Fixes" tag

Make sure the "images" folder exists and it's empty.

Work both with autotools- and meson- generated efl-mono dll.
Why are they called differently, anyway?

segfaultxavi added a comment.EditedDec 27 2018, 4:08 AM

Actually, for this to work with meson the docfx.json would need to be generated at configure time from a docfx.json.in. I've created a separate task for that (T7527)

Use source files instead of dll (so the name does not change between meson and autotools) and scan all folders from the root down (so will work for any meson builddir which is a subfolder of root)

Added EFL icon and favicon

lauromoura added inline comments.Dec 28 2018, 9:55 AM
docfx/README
12 ↗(On Diff #18121)

Shouldn't this be updated to something like "The API guide is generated from the EFL mono dll sources and its xmldoc tags"?

More precise README

segfaultxavi marked an inline comment as done.Dec 28 2018, 10:25 AM

Include note about mono in the README

Fix arc mess, doh!

lauromoura accepted this revision.Dec 28 2018, 10:43 AM
This revision is now accepted and ready to land.Dec 28 2018, 10:43 AM

Move docfx folder inside doc, where it makes more sense.

Will wait for somebody else's input before landing, as the scripts do several things and are bound to fail in some distro or another,

zmike added a comment.Jan 2 2019, 10:19 AM

I'm working on testing this.

bu5hm4n added inline comments.Jan 2 2019, 10:34 AM
doc/docfx/setup.sh
18

I am not too sure if we want to really download here without telling that to the user...

The normal way is installation via package manager, i could understand that a few users would be concerned that we *under the hood* download precompiled codes from somewhere, and execute it...

The alternative that i can think of is a seperated *install* script and a option to pass the docfx directory to the install script, or the generation script.

zmike added a comment.Jan 2 2019, 10:48 AM

I lied, it seems unlikely that I'll be able to test this. Fedora seems stuck on mono 4.8, which doesn't work with any of this.

OK, thanks @zmike, I'll try to find more "volunteers" for testing.

doc/docfx/setup.sh
18

Will a "Do you want to proceed with download?" message be enough?
DocFX does not appear in my apt search.
I am not too concerned about this since the use case for these scripts is: I execute them, obtain the HTML files, commit them somewhere, and end of the story.

zmike added a comment.Jan 2 2019, 11:30 AM

Hold on I'm attempting to build mono from git, stay tuned to this liveblog feed for continuing updates!

bu5hm4n accepted this revision.Jan 2 2019, 11:42 AM

it worked for me

@zmike See you in 4 months!

Detect mono version and skip DocFX download if bin folder already exists.

This revision was automatically updated to reflect the committed changes.