forked from enlightenment/efl
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
This commit is contained in:
parent
71776d2153
commit
2d8f3fba46
|
@ -0,0 +1,11 @@
|
|||
###############
|
||||
# folder #
|
||||
###############
|
||||
/**/DROP/
|
||||
/**/TEMP/
|
||||
/**/packages/
|
||||
/**/bin/
|
||||
/**/obj/
|
||||
_site
|
||||
images
|
||||
articles
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
###############
|
||||
# temp file #
|
||||
###############
|
||||
*.yml
|
||||
.manifest
|
|
@ -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.
|
|
@ -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
|
||||
}
|
||||
}
|
Binary file not shown.
After Width: | Height: | Size: 4.3 KiB |
|
@ -0,0 +1,7 @@
|
|||
apiRules:
|
||||
- include:
|
||||
uidRegex: ^Efl
|
||||
- include:
|
||||
uidRegex: ^Eina
|
||||
- exclude:
|
||||
uidRegex: ^.*
|
|
@ -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!"
|
|
@ -0,0 +1,2 @@
|
|||
# EFL C# Documentation site
|
||||
Use the top menu to access the API reference documentation and the tutorial guides.
|
|
@ -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 ..
|
|
@ -0,0 +1,5 @@
|
|||
- name: REFERENCE
|
||||
href: api/
|
||||
homepage: api/index.md
|
||||
- name: GUIDES
|
||||
href: articles/
|
Loading…
Reference in New Issue