efl/doc/docfx
Xavi Artigas 26e55458ad mono-docs: Update DocFX version and use online symbol lookup
Version 2.45 of DocFX seems much much faster than previous 2.40, but could just
be a matter of stale caches. Anyway, no breakages have been detected.
Using an online symbol resolution server (https://xref.docs.microsoft.com)
adds some more links for .NET symbols (and no noticeable slowdown).
2019-08-29 17:44:16 +02:00
..
api doc: Add support for DocFX (C# doc generator) 2019-01-07 17:07:42 +01:00
default_efl docfx: Missing template file 2019-07-29 16:15:55 +02:00
.gitignore doc: Add support for DocFX (C# doc generator) 2019-01-07 17:07:42 +01:00
README DocFX: Update README with Deployment instructions 2019-07-31 12:53:48 +02:00
docfx.json mono-docs: Update DocFX version and use online symbol lookup 2019-08-29 17:44:16 +02:00
e-logo-title.png doc: Add support for DocFX (C# doc generator) 2019-01-07 17:07:42 +01:00
filterConfig.yml mono-docs: More tweaks to the docs blacklist 2019-07-25 17:03:10 +02:00
gendoc.sh mono-docs: Use full name in list of derived classes 2019-04-23 10:51:56 +02:00
index.md doc: Add support for DocFX (C# doc generator) 2019-01-07 17:07:42 +01:00
setup.sh mono-docs: Update DocFX version and use online symbol lookup 2019-08-29 17:44:16 +02:00
toc.yml doc: Add support for DocFX (C# doc generator) 2019-01-07 17:07:42 +01:00

README

EFL DocFX SUPPORT
-----------------

DocFX (https://dotnet.github.io/docfx/) generates documentation HTML pages
directly from source code and Markdown files for C# projects.

Although significantly slow, it is a simple alternative while our own
documentation generator for C# is being written.

The scripts in this folder create a documentation site which contains the API
reference guide and articles with tutorials and guides.
The API guide is generated from the EFL mono sources, which are generated as
part of the normal build process.
The articles are fetched from the EFL www-content repository and adapted to
DocFX syntax.

USAGE
-----

First off, build EFL with C# support enabled so the C# sources are generated
(you will need to have mono 5 installed for this).
Then, from this folder, run the `setup.sh` script to download and extract the
DocFX binaries to the `bin` folder, fetch the articles from the `www-content`
repository and adapt them to the DocFX syntax.
Finally, run the `gendoc.sh` script (also from this folder) to produce the HTML
files. First run can take a long time (from 10' to 1h), subsequent runs use
cached results and take about 5 minutes.
The result can be found in the _site folder.

DEPLOYMENT
----------

This is the manual deployment process currently in use. It could certainly
be improved and automated.
The HTML files produced by DocFX are currently hosted using GitHub pages.
The Enlightenment site's content is hosted in the www-content repository:
https://git.enlightenment.org/website/www-content.git/
This repo is mirrored at GitHub:
https://github.com/Enlightenment/www-content
The GitHub mirror has a branch called "gh-pages" which has a "gh-pages"
folder at the root.

Whenever new documentation is generated, just copy the _site folder from
/doc/docfx in the EFL repo to /gh-pages/api/csharp in the www-content repo
(gh-pages branch!) and push to the GitHub mirror.
Changes should be visible almost instantly, since they are static pages.