From cc669c38382da93d57f65275ade48d5bf0177126 Mon Sep 17 00:00:00 2001 From: Roland Date: Thu, 27 Sep 2012 17:05:27 +0200 Subject: [PATCH] integrate akka-contrib docs into akka-docs build using the awesomized sbt-site plugin! --- .gitignore | 1 + akka-contrib/docs/conf.py | 85 ++++++++++++++++++++++++++++ akka-contrib/docs/reliable-proxy.rst | 12 ++-- akka-docs/rst/experimental/index.rst | 4 +- project/AkkaBuild.scala | 21 ++++++- 5 files changed, 114 insertions(+), 9 deletions(-) create mode 100644 akka-contrib/docs/conf.py diff --git a/.gitignore b/.gitignore index 42adcdec8d..f646a4c173 100755 --- a/.gitignore +++ b/.gitignore @@ -50,6 +50,7 @@ multiverse.log .*.swp akka-docs/_build/ akka-docs/rst_preprocessed/ +akka-contrib/rst_preprocessed/ *.pyc akka-docs/exts/ _akka_cluster/ diff --git a/akka-contrib/docs/conf.py b/akka-contrib/docs/conf.py new file mode 100644 index 0000000000..41d7ef783a --- /dev/null +++ b/akka-contrib/docs/conf.py @@ -0,0 +1,85 @@ +# -*- coding: utf-8 -*- +# +# Akka documentation build configuration file. +# + +import sys, os + +# -- General configuration ----------------------------------------------------- + +sys.path.append(os.path.abspath('../../akka-docs/_sphinx/exts')) +extensions = ['sphinx.ext.todo', 'includecode'] + +templates_path = ['_templates'] +source_suffix = '.rst' +master_doc = 'index' +exclude_patterns = ['_build', 'pending', 'disabled'] + +project = u'Akka' +copyright = u'2011, Typesafe Inc' +version = '@version@' +release = '@version@' + +pygments_style = 'simple' +highlight_language = 'scala' +add_function_parentheses = False +show_authors = True + +# -- Options for HTML output --------------------------------------------------- + +html_theme = 'akka' +html_theme_path = ['../../akka-docs/_sphinx/themes'] +html_favicon = '../../akka-docs/_sphinx/static/favicon.ico' + +html_title = 'Akka Documentation' +html_logo = '../../akka-docs/_sphinx/static/logo.png' +#html_favicon = None + +html_static_path = ['../../akka-docs/_sphinx/static'] + +html_last_updated_fmt = '%b %d, %Y' +#html_sidebars = {} +#html_additional_pages = {} +html_domain_indices = False +html_use_index = False +html_show_sourcelink = False +html_show_sphinx = False +html_show_copyright = True +htmlhelp_basename = 'Akkadoc' +html_use_smartypants = False +html_add_permalinks = '' + +html_context = { + 'include_analytics': 'online' in tags +} + +# -- Options for EPUB output --------------------------------------------------- +epub_author = "Typesafe Inc" +epub_language = "en" +epub_publisher = epub_author +epub_identifier = "http://doc.akka.io/docs/akka/snapshot/" +epub_scheme = "URL" +epub_cover = ("../../akka-docs/_sphinx/static/akka.png", "") + +# -- Options for LaTeX output -------------------------------------------------- + +def setup(app): + from sphinx.util.texescape import tex_replacements + tex_replacements.append((u'⇒', ur'\(\Rightarrow\)')) + +latex_paper_size = 'a4' +latex_font_size = '10pt' + +latex_documents = [ + ('index', 'Akka.tex', u' Akka Documentation', + u'Typesafe Inc', 'manual'), +] + +latex_elements = { + 'classoptions': ',oneside,openany', + 'babel': '\\usepackage[english]{babel}', + 'fontpkg': '\\PassOptionsToPackage{warn}{textcomp} \\usepackage{times}', + 'preamble': '\\definecolor{VerbatimColor}{rgb}{0.935,0.935,0.935}' + } + +# latex_logo = '_sphinx/static/akka.png' diff --git a/akka-contrib/docs/reliable-proxy.rst b/akka-contrib/docs/reliable-proxy.rst index add4fa0340..af87255a2f 100644 --- a/akka-contrib/docs/reliable-proxy.rst +++ b/akka-contrib/docs/reliable-proxy.rst @@ -60,7 +60,7 @@ communication channel. The benefit is that the network in-between is taken out of that equation. When the target actor terminates, the proxy will terminate as well (on the -terms of :ref:`deathwatch-java` / :ref:`deathwath-scala`). +terms of :ref:`deathwatch-java` / :ref:`deathwatch-scala`). How to use it ------------- @@ -69,12 +69,12 @@ Since this implementation does not offer much in the way of configuration, simply instantiate a proxy wrapping some target reference. From Java it looks like this: -.. includecode:: ../src/test/java/akka/contrib/pattern/ReliableProxyTest.java#imports -.. includecode:: ../src/test/java/akka/contrib/pattern/ReliableProxyTest.java#demo-proxy +.. includecode:: @contribSrc@/src/test/java/akka/contrib/pattern/ReliableProxyTest.java#import +.. includecode:: @contribSrc@/src/test/java/akka/contrib/pattern/ReliableProxyTest.java#demo-proxy And from Scala like this: -.. includecode:: ../src/multi-jvm/scala/akka/contrib/pattern/ReliableProxySpec.scala#demo +.. includecode:: @contribSrc@/src/multi-jvm/scala/akka/contrib/pattern/ReliableProxySpec.scala#demo Since the :class:`ReliableProxy` actor is an :ref:`fsm-scala`, it also offers the capability to subscribe to state transitions. If you need to know when all @@ -83,10 +83,10 @@ been forwarded to the target), you can subscribe to the FSM notifications and observe a transition from state :class:`ReliableProxy.Active` to state :class:`ReliableProxy.Idle`. -.. includecode:: ../src/test/java/akka/contrib/pattern/ReliableProxyTest.java#demo-transition +.. includecode:: @contribSrc@/src/test/java/akka/contrib/pattern/ReliableProxyTest.java#demo-transition From Scala it would look like so: -.. includecode:: ../src/test/scala/akka/contrib/pattern/ReliableProxyDocSpec.scala#demo-transition +.. includecode:: @contribSrc@/src/test/scala/akka/contrib/pattern/ReliableProxyDocSpec.scala#demo-transition diff --git a/akka-docs/rst/experimental/index.rst b/akka-docs/rst/experimental/index.rst index 47339a8fb0..9a62d3e035 100644 --- a/akka-docs/rst/experimental/index.rst +++ b/akka-docs/rst/experimental/index.rst @@ -27,7 +27,7 @@ to tell if the module has a maintainer that can take the responsibility of the module over time. These modules live in the ``akka-contrib`` subproject: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - ../b/../../../akka-contrib/docs/index.rst + ../contrib/index diff --git a/project/AkkaBuild.scala b/project/AkkaBuild.scala index e5bd091b00..f6c84e6f29 100644 --- a/project/AkkaBuild.scala +++ b/project/AkkaBuild.scala @@ -354,6 +354,18 @@ object AkkaBuild extends Build { settings = defaultSettings ++ SphinxSupport.settings ++ sphinxPreprocessing ++ cpsPlugin ++ Seq( sourceDirectory in Sphinx <<= baseDirectory / "rst", sphinxPackages in Sphinx <+= baseDirectory { _ / "_sphinx" / "pygments" }, + // copy akka-contrib/docs into our rst_preprocess/contrib (and apply substitutions) + preprocess in Sphinx <<= (preprocess in Sphinx, + sourceDirectory in contrib in Sphinx, + target in preprocess in Sphinx, + cacheDirectory, + preprocessExts in Sphinx, + preprocessVars in Sphinx, + streams) map { (orig, src, target, cacheDir, exts, vars, s) => + val contribSrc = Map("contribSrc" -> "../../../akka-contrib") + simplePreprocess(src, target / "contrib", cacheDir / "sphinx" / "preprocessed-contrib", exts, vars ++ contribSrc, s.log) + orig + }, enableOutput in generatePdf in Sphinx := true, unmanagedSourceDirectories in Test <<= sourceDirectory in Sphinx apply { _ ** "code" get }, libraryDependencies ++= Dependencies.docs, @@ -366,9 +378,16 @@ object AkkaBuild extends Build { id = "akka-contrib", base = file("akka-contrib"), dependencies = Seq(remote, remoteTests % "compile;test->test"), - settings = defaultSettings ++ multiJvmSettings ++ Seq( + settings = defaultSettings ++ multiJvmSettings ++ SphinxSupport.settings ++ sphinxPreprocessing ++ Seq( libraryDependencies ++= Dependencies.contrib, testOptions += Tests.Argument(TestFrameworks.JUnit, "-v"), + preprocessVars in Sphinx <<= (preprocessVars in Sphinx) { (old) => + old ++ Map( + "contribSrc" -> ".." + ) + }, + sourceDirectory in Sphinx <<= baseDirectory / "docs", + sphinxPackages in Sphinx <+= baseDirectory { _ / ".." / "akka-docs" / "_sphinx" / "pygments" }, description := """| |This subproject provides a home to modules contributed by external |developers which may or may not move into the officially supported code