aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorXavi Artigas <xavierartigas@yahoo.es>2018-11-06 15:21:03 +0100
committerXavi Artigas <xavierartigas@yahoo.es>2019-01-07 17:07:42 +0100
commit2d8f3fba464411329eadcf41d02d542f2f4e339c (patch)
tree509a8fea41a0df8acea64f17a7786c291519cb23
parentevas vg: don't draw invisible nodes. (diff)
downloadefl-2d8f3fba464411329eadcf41d02d542f2f4e339c.tar.gz
doc: Add support for DocFX (C# doc generator)
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. Reviewers: lauromoura, bu5hm4n, cedric, myoungwoon, zmike Reviewed By: lauromoura, bu5hm4n Subscribers: #reviewers, #committers Tags: #efl Maniphest Tasks: https://phab.enlightenment.org/T7424 Differential Revision: https://phab.enlightenment.org/D7502
-rw-r--r--doc/docfx/.gitignore11
-rw-r--r--doc/docfx/README28
-rw-r--r--doc/docfx/api/.gitignore5
-rw-r--r--doc/docfx/api/index.md5
-rw-r--r--doc/docfx/docfx.json73
-rw-r--r--doc/docfx/e-logo-title.pngbin0 -> 4441 bytes
-rw-r--r--doc/docfx/filterConfig.yml7
-rwxr-xr-xdoc/docfx/gendoc.sh26
-rw-r--r--doc/docfx/index.md2
-rwxr-xr-xdoc/docfx/setup.sh100
-rw-r--r--doc/docfx/toc.yml5
11 files changed, 262 insertions, 0 deletions
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
--- /dev/null
+++ b/doc/docfx/e-logo-title.png
Binary files 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 <see> 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 <xref href="">
+# tags).
+for f in `ls api/*.yml`; do
+ sed -e 's/\(<xref href="[^"]*\)"/\1?displayProperty=fullName"/g' -i $f
+ sed -e 's/\(<xref href=\\"[^\\]*\)\\"/\1?displayProperty=fullName\\"/g' -i $f
+done;
+
+# DocFX Step 2: Generate HTML files
+mono bin/docfx.exe build docfx.json && echo "Docs ready in the _site folder!"
diff --git a/doc/docfx/index.md b/doc/docfx/index.md
new file mode 100644
index 0000000000..6494f8b893
--- /dev/null
+++ b/doc/docfx/index.md
@@ -0,0 +1,2 @@
+# EFL C# Documentation site
+Use the top menu to access the API reference documentation and the tutorial guides.
diff --git a/doc/docfx/setup.sh b/doc/docfx/setup.sh
new file mode 100755
index 0000000000..eb15787c2e
--- /dev/null
+++ b/doc/docfx/setup.sh
@@ -0,0 +1,100 @@
+#!/bin/bash
+#
+# This script installs DocFX and brings all content pages from EFL's documentation
+# content repository, transforming them from DokuWiki's format to DocFX's.
+# This step only needs to be done once (or every time the content pages change).
+# After this step, you can run the gendoc.sh script as many times as you want,
+# to generate the actual HTML pages, including the reference guide extracted from
+# libefl_mono.dll and libefl_mono.xml
+#
+# This script could be improved a lot, but it gets the job done.
+# Xavi (xartigas@yahoo.es)
+
+#
+# Check mono version since DocFX has been known to fail with mono 4.
+#
+mono_version="$(mono --version | awk '/version/ { print $5 }')"
+if [ $mono_version \< 5 ];
+then
+ echo "Requires at least mono version 5, detected $mono_version"
+ exit 1
+fi;
+
+#
+# Download and extract DocFX
+#
+if [ ! -d "bin" ]; then
+ rm -rf docfx.zip bin
+ wget https://github.com/dotnet/docfx/releases/download/v2.40.4/docfx.zip
+ unzip -q docfx.zip -d bin
+ rm docfx.zip
+else
+ echo "Skipping DocFX download because 'bin' folder already exists."
+fi
+
+#
+# Clone whole Content site
+#
+rm -rf www-content
+git clone --depth 1 git+ssh://git@git.enlightenment.org/website/www-content.git www-content
+
+#
+# Copy all pages related to C# (those inside a folder called 'csharp') to the articles folder
+#
+rm -rf articles
+mkdir articles
+# Copy them
+find www-content -wholename "*/csharp/*.md.txt" -exec cp --parents {} articles \;
+# Except tutorials and guides summary pages (start.md)
+find articles/www-content/pages/develop/tutorials -name "start.md.txt" -exec rm {} \;
+find articles/www-content/pages/develop/guides -name "start.md.txt" -exec rm {} \;
+# Remove the trailing .txt from filenames (DocFX wants only the .md)
+for f in `find articles -name "*.md.txt"`; do mv $f $(echo $f | rev | cut -c5- | rev) ; done
+# Copy all media files to the images folder
+rm -rf images
+mkdir images
+cp -r www-content/media/* images
+# Remove git clone now that we have everything we wanted
+rm -rf www-content
+
+#
+# Parse all Markdown files to adapt them to DocFX
+#
+# Remove special Dokuwiki headers like ~~NOCACHE~~ because DocFX complains about them.
+find articles -name "*.md" | xargs sed -i -e "s/^~~.*~~$//g"
+# Transform media links in articles from /_media/* to ~/images/*
+find articles -name "*.md" | xargs sed -i -e "s#/_media#~/images#g"
+# Transform API root links from /develop/api/ to @api-reference-root (the UID of the API root)
+find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\](\)/develop/api/)#\1xref:api-reference-root)#g"
+# Transform API class links from */api/namespace/class to @Namespace.Class (that should be the UID of the reference page)
+find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\](\)[^)]*/api/\([^/.]*\)/\([^/.]*\))#\1xref:\u\2.\u\3)#g"
+# Point links to Legacy API to the www.enlightenment.org site
+find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\](\)\(/develop/legacy/api/[^)]*)\)#\1https://www.enlightenment.org\2#g"
+# Point the rest of links to /develop/api/* to the root the API, since we don't know how to transform them
+find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\](\)/develop/api/[^)]*)#\1xref:api-reference-root)#g"
+# Add start.md to links pointing to a folder inside ~/develop/
+find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\](/develop/[^)]*/\))#\1start.md)#g"
+# Transform absolute links from /develop/* to ~/articles/www-content/pages/develop/*
+find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\]\)(\(/develop/[^)]*\))#\1(~/articles/www-content/pages\2)#g"
+# Transform page anchor links from [label](#Anchor_Title) to [label](#anchor-title).
+for f in `find articles -name "*.md"`; do
+ awk -v RS=' ' '{ if ($0 ~ ".*\(#.*\)") { gsub( /_/, "-" ); printf "%s ", tolower($0) } else { printf "%s ",$0 } }' $f > /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/