ドキュメンテーションシステム Hello World¶

Fabric Engine version 2.4.0

この例ではエクステンションを作成し、そこにドキュメントを付してみます。つまりは HelloWorld ですね。まずはエクステンションを配する HelloWorld フォルダを作成し、以下の２ファイルを追加します：

HelloWorld.fpm.json :

{
  "version": "1.0.0",
  "code": [
    "HelloWorld.kl"
  ]
}

HelloWorld.kl :

/// A function to print out HelloWorld
/// \example
///   // prints out hello world
///   printHelloWorld();
/// \endexample
function printHelloWorld() {
  report('Hello World!');
}

もちろん sphinx のため conf.py ファイルも必要ですね。以下のようにしてみましょう（詳細は sphinx 自身のドキュメントに譲ります）

import os
import FabricEngine.Sphinx.KL

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
  'sphinx.ext.autodoc',
  'sphinx.ext.graphviz',
  'FabricEngine.Sphinx.KL',
  'FabricEngine.Sphinx.DFG'
]

# Find exectuable in PATH
def which(program):
    def is_exe(fpath):
        return os.path.isfile(fpath) and os.access(fpath, os.X_OK)

    fpath, fname = os.path.split(program)
    if fpath:
        if is_exe(program):
            return program
    else:
        for path in os.environ["PATH"].split(os.pathsep):
            path = path.strip('"')
            exe_file = os.path.join(path, program)
            if is_exe(exe_file):
                return exe_file

    return None

# location of the graphviz dot file
buildOS = os.environ['FABRIC_BUILD_OS']
if buildOS == 'Windows':
  graphviz_dot = which("dot.exe")
else:
  graphviz_dot = which("dot")

if not graphviz_dot:
  raise Exception("Missing 'dot' executable. Check that GraphViz is installed and that dot.exe cam be found. Define an environment variable GRAPHVIZ_DOT_BIN which points to dot.exe")
graphviz_output_format = 'svg'

# The suffix of source filenames.
source_suffix = '.rst'

# The master toctree document.
master_doc = 'index'

# General information about the project.
project = u'My project'
copyright = u'My company copyright'

# The short X.Y version.
version = '1.0.0'
# The full version, including alpha/beta/rc tags.
release = '1.0.0'

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'default'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
fabric_color_sky_blue = "#21a8e0"
fabric_color_greenish = "#73992b"
fabric_color_aubergine = "#2e1a2e"
fabric_color_33pct_gray = "#a8a8a8"
fabric_color_15pct_gray = "#dadada"
fabric_color_black = "#000000"
html_theme_options = {
  "headbgcolor": fabric_color_15pct_gray,
  "headtextcolor": fabric_color_aubergine,
  "sidebarbgcolor": fabric_color_aubergine,
  "sidebartextcolor": fabric_color_33pct_gray,
  "sidebarlinkcolor": fabric_color_15pct_gray,
  "relbarbgcolor": fabric_color_greenish,
  "relbartextcolor": fabric_color_15pct_gray,
  "relbarlinkcolor": fabric_color_aubergine,
  "footerbgcolor": fabric_color_black,
  "footertextcolor": fabric_color_33pct_gray,
}

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
html_title = "My project Documentation"

index.rst ファイルも必要です：

.. _TOP:

My project Documentation
=========================================

Welcome!
---------------------

This is the documentation for My project.


Table of contents
---------------------------------

.. toctree::
  :maxdepth: 1

  extensions/index

見てわかるようにここで index.rst ファイルを extensions サブフォルダ内で参照しています。すべてのエクステンションのドキュメントがここに生成されます。このように他のセクションのドキュメントをさらに他へと文書埋め込み可能です。 extensions/index.rst :

My project Extensions
==================================

Table of Contents
-----------------

.. kl-extlist:: extensions

カスタムKL構文を使用していますね。この構文は見つかった全エクステンションの目次（toc）を自動生成します。

最後に、つぎのヘルパスクリプトを使用し、ドキュメントを生成できます。勿論各種パスは調整してください。

import os
import sphinx

from ASTWrapper import *

# note: the extsDir also has to be on the FABRIC_EXTS_PATH env var
extsDir = 'c:\\temp\\exts'
tmpDir = 'c:\\temp\\build'
srcDir = 'c:\\temp\\source'
extSrcDir = os.path.join(srcDir, 'Extensions')
stageDir = 'c:\\temp\\docs'


for d in [tmpDir, srcDir, stageDir]:
  if not os.path.exists(d):
    os.makedirs(d)

    os.environ['RST_DOC_SOURCE_EXTS_DIR'] = os.path.join(stageDir, 'Extensions')
os.environ['RST_DOC_TARGET_EXTS_DIR'] = extSrcDir

# create the ast manager
manager = KLManager(paths = [extsDir], header = [])

# create all extension rst files
extensions = manager.getKLExtensions()
for extension in extensions:
  extSrcDir = os.path.join(extSrcDir, extension.getName())
  if not os.path.exists(extSrcDir):
    os.makedirs(extSrcDir)
  extTmpDir = os.path.join(tmpDir, extension.getName())
  if not os.path.exists(extTmpDir):
    os.makedirs(extTmpDir)
  manager.generateKLExtensionRST(extension, extSrcDir, extTmpDir)

# invoke sphinx
sphinx.main(['-b html', '-E', '-a', srcDir, stageDir])

ドキュメンテーションシステム Hello World¶

目次¶

目次

前のトピックへ

次のトピックへ

このページ