diff --git a/doc/docfx/.gitignore b/doc/docfx/.gitignore new file mode 100644 index 0000000000..24c4621b34 --- /dev/null +++ b/doc/docfx/.gitignore @@ -0,0 +1,11 @@ +############### +# folder # +############### +/**/DROP/ +/**/TEMP/ +/**/packages/ +/**/bin/ +/**/obj/ +_site +images +articles diff --git a/doc/docfx/README b/doc/docfx/README new file mode 100644 index 0000000000..a35110cccf --- /dev/null +++ b/doc/docfx/README @@ -0,0 +1,28 @@ +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. + diff --git a/doc/docfx/api/.gitignore b/doc/docfx/api/.gitignore new file mode 100644 index 0000000000..f798527e61 --- /dev/null +++ b/doc/docfx/api/.gitignore @@ -0,0 +1,5 @@ +############### +# temp file # +############### +*.yml +.manifest diff --git a/doc/docfx/api/index.md b/doc/docfx/api/index.md new file mode 100644 index 0000000000..2965aa1aaa --- /dev/null +++ b/doc/docfx/api/index.md @@ -0,0 +1,5 @@ +--- +uid: api-reference-root +--- +# EFL C# API reference documentation +Use the menu on the left to select a namespace or class. diff --git a/doc/docfx/docfx.json b/doc/docfx/docfx.json new file mode 100644 index 0000000000..1c5009de69 --- /dev/null +++ b/doc/docfx/docfx.json @@ -0,0 +1,73 @@ +{ + "metadata": [ + { + "src": [ + { + "src": "../..", + "files": [ + "**/*.cs" + ] + } + ], + "dest": "api", + "filter": "filterConfig.yml", + "disableGitFeatures": false, + "disableDefaultFilter": false + } + ], + "build": { + "content": [ + { + "files": [ + "api/**.yml", + "api/index.md" + ] + }, + { + "files": [ + "articles/**.md", + "articles/**/toc.yml", + "toc.yml", + "*.md" + ] + } + ], + "resource": [ + { + "files": ["e-logo-title.png"] + }, + { + "files": [ + "images/**" + ] + } + ], + "overwrite": [ + { + "files": [ + "apidoc/**.md" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + } + ], + "globalMetadata": { + "_appLogoPath": "e-logo-title.png", + "_appFaviconPath": "e-logo-title.png" + }, + "dest": "_site", + "globalMetadataFiles": [], + "fileMetadataFiles": [], + "template": [ + "default" + ], + "postProcessors": [], + "markdownEngineName": "markdig", + "noLangKeyword": false, + "keepFileLink": false, + "cleanupCacheHistory": false, + "disableGitFeatures": false + } +} diff --git a/doc/docfx/e-logo-title.png b/doc/docfx/e-logo-title.png new file mode 100644 index 0000000000..508915f635 Binary files /dev/null and b/doc/docfx/e-logo-title.png differ diff --git a/doc/docfx/filterConfig.yml b/doc/docfx/filterConfig.yml new file mode 100644 index 0000000000..3fe441259a --- /dev/null +++ b/doc/docfx/filterConfig.yml @@ -0,0 +1,7 @@ +apiRules: +- include: + uidRegex: ^Efl +- include: + uidRegex: ^Eina +- exclude: + uidRegex: ^.* diff --git a/doc/docfx/gendoc.sh b/doc/docfx/gendoc.sh new file mode 100755 index 0000000000..99da2d9f18 --- /dev/null +++ b/doc/docfx/gendoc.sh @@ -0,0 +1,26 @@ +#!/bin/bash + +# This script invokes the locally-installed DocFX to produce the reference +# documentation. Run it every time EO documentation changes. + +# DocFX Step 1: Generate metadata (*.yml) files +mono bin/docfx.exe metadata docfx.json + +# Process the generated metadata files: +# DocFX uses short names for all links which is inconvenient for us +# because we have multiple types with the same name in different namespaces +# ("Object" can be "Efl.Object" or "Efl.Canvas.Object"). +# MarkDown files can add "?displayProperty=fullName" to crefs to show them +# fully-qualified, but this is stripped out from triple-slash comments in C# +# source files. +# +# This script adds the displayProperty suffix to all cref links from the +# metadata yml files (by that time links have been turned into +# tags). +for f in `ls api/*.yml`; do + sed -e 's/\( /tmp/efl_docfx_setup.tmp + mv /tmp/efl_docfx_setup.tmp $f +done + +# +# Populate articles TOC file from the articles' titles +# +cd articles +rm -f toc.yml +echo "- name: Setup Guide" >> toc.yml +echo " href: www-content/pages/develop/setup/csharp/start.md" >> toc.yml +echo "- name: Tutorials" >> toc.yml +echo " items:" >> toc.yml +find www-content/pages/develop/tutorials -name "*.md" -exec sh -c "cat {} | grep '^# ' && echo ' href: {}'" \; >> toc.yml +echo "- name: Guides" >> toc.yml +echo " items:" >> toc.yml +find www-content/pages/develop/guides -name "*.md" -exec sh -c "cat {} | grep '^# ' && echo ' href: {}'" \; >> toc.yml +sed -i -e "s/^# \(.*\) #/ - name: '\1'/g" toc.yml +sed -i -e "s/ in C#//g" toc.yml +cd .. diff --git a/doc/docfx/toc.yml b/doc/docfx/toc.yml new file mode 100644 index 0000000000..6aa545deb2 --- /dev/null +++ b/doc/docfx/toc.yml @@ -0,0 +1,5 @@ +- name: REFERENCE + href: api/ + homepage: api/index.md +- name: GUIDES + href: articles/