forked from enlightenment/efl
47 lines
1.9 KiB
Plaintext
47 lines
1.9 KiB
Plaintext
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.
|