summaryrefslogtreecommitdiff
path: root/doc
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 /doc
parent71776d2153d44657673aaf944c02b687b3b11d1b (diff)
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: T7424 Differential Revision: https://phab.enlightenment.org/D7502
Diffstat (limited to 'doc')
-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 @@
1###############
2# folder #
3###############
4/**/DROP/
5/**/TEMP/
6/**/packages/
7/**/bin/
8/**/obj/
9_site
10images
11articles
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 @@
1EFL DocFX SUPPORT
2-----------------
3
4DocFX (https://dotnet.github.io/docfx/) generates documentation HTML pages
5directly from source code and Markdown files for C# projects.
6
7Although significantly slow, it is a simple alternative while our own
8documentation generator for C# is being written.
9
10The scripts in this folder create a documentation site which contains the API
11reference guide and articles with tutorials and guides.
12The API guide is generated from the EFL mono sources, which are generated as
13part of the normal build process.
14The articles are fetched from the EFL www-content repository and adapted to
15DocFX syntax.
16
17USAGE
18-----
19
20First off, build EFL with C# support enabled so the C# sources are generated
21(you will need to have mono 5 installed for this).
22Then, from this folder, run the `setup.sh` script to download and extract the
23DocFX binaries to the `bin` folder, fetch the articles from the `www-content`
24repository and adapt them to the DocFX syntax.
25Finally, run the `gendoc.sh` script (also from this folder) to produce the HTML
26files. First run can take a long time (from 10' to 1h), subsequent runs use
27cached results and take about 5 minutes.
28
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 @@
1###############
2# temp file #
3###############
4*.yml
5.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 @@
1---
2uid: api-reference-root
3---
4# EFL C# API reference documentation
5Use 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 @@
1{
2 "metadata": [
3 {
4 "src": [
5 {
6 "src": "../..",
7 "files": [
8 "**/*.cs"
9 ]
10 }
11 ],
12 "dest": "api",
13 "filter": "filterConfig.yml",
14 "disableGitFeatures": false,
15 "disableDefaultFilter": false
16 }
17 ],
18 "build": {
19 "content": [
20 {
21 "files": [
22 "api/**.yml",
23 "api/index.md"
24 ]
25 },
26 {
27 "files": [
28 "articles/**.md",
29 "articles/**/toc.yml",
30 "toc.yml",
31 "*.md"
32 ]
33 }
34 ],
35 "resource": [
36 {
37 "files": ["e-logo-title.png"]
38 },
39 {
40 "files": [
41 "images/**"
42 ]
43 }
44 ],
45 "overwrite": [
46 {
47 "files": [
48 "apidoc/**.md"
49 ],
50 "exclude": [
51 "obj/**",
52 "_site/**"
53 ]
54 }
55 ],
56 "globalMetadata": {
57 "_appLogoPath": "e-logo-title.png",
58 "_appFaviconPath": "e-logo-title.png"
59 },
60 "dest": "_site",
61 "globalMetadataFiles": [],
62 "fileMetadataFiles": [],
63 "template": [
64 "default"
65 ],
66 "postProcessors": [],
67 "markdownEngineName": "markdig",
68 "noLangKeyword": false,
69 "keepFileLink": false,
70 "cleanupCacheHistory": false,
71 "disableGitFeatures": false
72 }
73}
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 @@
1apiRules:
2- include:
3 uidRegex: ^Efl
4- include:
5 uidRegex: ^Eina
6- exclude:
7 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 @@
1#!/bin/bash
2
3# This script invokes the locally-installed DocFX to produce the reference
4# documentation. Run it every time EO documentation changes.
5
6# DocFX Step 1: Generate metadata (*.yml) files
7mono bin/docfx.exe metadata docfx.json
8
9# Process the generated metadata files:
10# DocFX uses short names for all <see> links which is inconvenient for us
11# because we have multiple types with the same name in different namespaces
12# ("Object" can be "Efl.Object" or "Efl.Canvas.Object").
13# MarkDown files can add "?displayProperty=fullName" to crefs to show them
14# fully-qualified, but this is stripped out from triple-slash comments in C#
15# source files.
16#
17# This script adds the displayProperty suffix to all cref links from the
18# metadata yml files (by that time links have been turned into <xref href="">
19# tags).
20for f in `ls api/*.yml`; do
21 sed -e 's/\(<xref href="[^"]*\)"/\1?displayProperty=fullName"/g' -i $f
22 sed -e 's/\(<xref href=\\"[^\\]*\)\\"/\1?displayProperty=fullName\\"/g' -i $f
23done;
24
25# DocFX Step 2: Generate HTML files
26mono 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 @@
1# EFL C# Documentation site
2Use 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 @@
1#!/bin/bash
2#
3# This script installs DocFX and brings all content pages from EFL's documentation
4# content repository, transforming them from DokuWiki's format to DocFX's.
5# This step only needs to be done once (or every time the content pages change).
6# After this step, you can run the gendoc.sh script as many times as you want,
7# to generate the actual HTML pages, including the reference guide extracted from
8# libefl_mono.dll and libefl_mono.xml
9#
10# This script could be improved a lot, but it gets the job done.
11# Xavi (xartigas@yahoo.es)
12
13#
14# Check mono version since DocFX has been known to fail with mono 4.
15#
16mono_version="$(mono --version | awk '/version/ { print $5 }')"
17if [ $mono_version \< 5 ];
18then
19 echo "Requires at least mono version 5, detected $mono_version"
20 exit 1
21fi;
22
23#
24# Download and extract DocFX
25#
26if [ ! -d "bin" ]; then
27 rm -rf docfx.zip bin
28 wget https://github.com/dotnet/docfx/releases/download/v2.40.4/docfx.zip
29 unzip -q docfx.zip -d bin
30 rm docfx.zip
31else
32 echo "Skipping DocFX download because 'bin' folder already exists."
33fi
34
35#
36# Clone whole Content site
37#
38rm -rf www-content
39git clone --depth 1 git+ssh://git@git.enlightenment.org/website/www-content.git www-content
40
41#
42# Copy all pages related to C# (those inside a folder called 'csharp') to the articles folder
43#
44rm -rf articles
45mkdir articles
46# Copy them
47find www-content -wholename "*/csharp/*.md.txt" -exec cp --parents {} articles \;
48# Except tutorials and guides summary pages (start.md)
49find articles/www-content/pages/develop/tutorials -name "start.md.txt" -exec rm {} \;
50find articles/www-content/pages/develop/guides -name "start.md.txt" -exec rm {} \;
51# Remove the trailing .txt from filenames (DocFX wants only the .md)
52for f in `find articles -name "*.md.txt"`; do mv $f $(echo $f | rev | cut -c5- | rev) ; done
53# Copy all media files to the images folder
54rm -rf images
55mkdir images
56cp -r www-content/media/* images
57# Remove git clone now that we have everything we wanted
58rm -rf www-content
59
60#
61# Parse all Markdown files to adapt them to DocFX
62#
63# Remove special Dokuwiki headers like ~~NOCACHE~~ because DocFX complains about them.
64find articles -name "*.md" | xargs sed -i -e "s/^~~.*~~$//g"
65# Transform media links in articles from /_media/* to ~/images/*
66find articles -name "*.md" | xargs sed -i -e "s#/_media#~/images#g"
67# Transform API root links from /develop/api/ to @api-reference-root (the UID of the API root)
68find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\](\)/develop/api/)#\1xref:api-reference-root)#g"
69# Transform API class links from */api/namespace/class to @Namespace.Class (that should be the UID of the reference page)
70find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\](\)[^)]*/api/\([^/.]*\)/\([^/.]*\))#\1xref:\u\2.\u\3)#g"
71# Point links to Legacy API to the www.enlightenment.org site
72find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\](\)\(/develop/legacy/api/[^)]*)\)#\1https://www.enlightenment.org\2#g"
73# Point the rest of links to /develop/api/* to the root the API, since we don't know how to transform them
74find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\](\)/develop/api/[^)]*)#\1xref:api-reference-root)#g"
75# Add start.md to links pointing to a folder inside ~/develop/
76find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\](/develop/[^)]*/\))#\1start.md)#g"
77# Transform absolute links from /develop/* to ~/articles/www-content/pages/develop/*
78find articles -name "*.md" | xargs sed -i -e "s#\(\[[^]]*\]\)(\(/develop/[^)]*\))#\1(~/articles/www-content/pages\2)#g"
79# Transform page anchor links from [label](#Anchor_Title) to [label](#anchor-title).
80for f in `find articles -name "*.md"`; do
81 awk -v RS=' ' '{ if ($0 ~ ".*\(#.*\)") { gsub( /_/, "-" ); printf "%s ", tolower($0) } else { printf "%s ",$0 } }' $f > /tmp/efl_docfx_setup.tmp
82 mv /tmp/efl_docfx_setup.tmp $f
83done
84
85#
86# Populate articles TOC file from the articles' titles
87#
88cd articles
89rm -f toc.yml
90echo "- name: Setup Guide" >> toc.yml
91echo " href: www-content/pages/develop/setup/csharp/start.md" >> toc.yml
92echo "- name: Tutorials" >> toc.yml
93echo " items:" >> toc.yml
94find www-content/pages/develop/tutorials -name "*.md" -exec sh -c "cat {} | grep '^# ' && echo ' href: {}'" \; >> toc.yml
95echo "- name: Guides" >> toc.yml
96echo " items:" >> toc.yml
97find www-content/pages/develop/guides -name "*.md" -exec sh -c "cat {} | grep '^# ' && echo ' href: {}'" \; >> toc.yml
98sed -i -e "s/^# \(.*\) #/ - name: '\1'/g" toc.yml
99sed -i -e "s/ in C#//g" toc.yml
100cd ..
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 @@
1- name: REFERENCE
2 href: api/
3 homepage: api/index.md
4- name: GUIDES
5 href: articles/