Add some targets for making a README

usersguide-sphinx/Makefile

@@ -21,7 +21,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext readme
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -246,3 +246,9 @@ source/media/omedit-icons/%.pdf: source/media/omedit-icons/%.svg
 source/media/omoptim-icons/%.png: $(OPENMODELICAHOME)/../OMOptim/OMOptim/GUI/Resources/icons/%.png
 	@mkdir -p source/media/omoptim-icons
 	cp -a "$<" "$@"
+
+readme/sphinxcontribopenmodelica.py: source/sphinxcontribopenmodelica.py
+	cp -a "$<" "$@"
+readme: readme/sphinxcontribopenmodelica.py
+	ln -sf ../source/aplot.svg readme
+	sphinx-build -b html -t nomathjax -d build/readme/doctrees readme build/readme/html

usersguide-sphinx/readme/README.2.rst

@@ -0,0 +1,6 @@
+Second chapter
+==============
+
+It is possible to have text in multiple chapters, including
+:index:`cross-references <cross-reference>` to another chapter, such
+as :numref:`simulate-command`.

usersguide-sphinx/readme/README.rst

@@ -0,0 +1,104 @@
+How to edit reST
+================
+
+Above is how to mark a chapter heading.
+The next levels use dashes (-), tilde (~), and circumflex (^).
+Really, any format works, but this is the default for editing the
+OpenModelica User's Guide (except for some files that include other
+rst-files, where other characters are used).
+
+Syntax highlighting and running commands
+----------------------------------------
+
+In order to mark something as code, use \`some code\`, i.e. `some code`.
+It is also possible to mark commands being run:
+
+  >>> 1+1
+  2
+
+You can create a code block that is syntax-highlighted according to the
+programming language of your choice by using a code-block block.
+
+.. code-block :: modelica
+
+  model M
+    Real r(start=0, fixed=true);
+  equation
+    der(r) = 1.0;
+  end M;
+
+It is also possible to load a model into OMC.
+
+.. omc-loadString ::
+
+  model M
+    Real r(start=2, fixed=true);
+  equation
+    der(r) = -r^2;
+  end M;
+
+You can then run the commands using the omc-mos block. It takes the same
+options as a code-block (on the generated code). It also takes a few
+custom options:
+
+noerror
+  Does not call getErrorString after each command.
+clear
+  Calls clear() before the first command.
+parsed
+  Uses the OMPython parser to create Python data types instead of strings.
+combine-lines
+  Used to merge multiple lines of input into a single command.
+erroratend
+  Calls getErrorString at the end, generating a sphinx Error box.
+hidden
+  Does not generate output (can be used to generate some data for later
+  inclusion.
+ompython-output
+  Special commands for generating OMPython documentation.
+
+.. omc-mos ::
+  :name: simulate-command
+  :caption: A simulate command.
+
+  simulate(M, stopTime=10)
+
+You can also plot the generated results using an omc-gnuplot block.
+This takes one argument (the name to use for the generated plot), and
+has a few custom options:
+
+filename
+  The path of the file to plot (default: last successful simulation)
+caption
+  Generates a caption for the plot figure.
+name
+  Generates a label for the plot figure.
+parametric
+  Do a parametric plot.
+plotall
+  Plot all variables.
+
+.. omc-gnuplot :: aplot
+  :caption: A plot.
+  :name: plot
+
+  r
+
+At the end of the page, restart OMPython to ensure that the same results
+are given every time you compile the document.
+
+.. omc-reset ::
+
+.. _cross-refs :
+
+Cross-References
+----------------
+
+It is possible to references figures and sections given that there is a
+label. Reference sections such as :ref:`cross-refs` using the ref role.
+Figures, Tables, and Listings can be referenced using the ref and numref
+roles :ref:`plot` is :numref:`plot`. :ref:`simulate-command` refers to
+:numref:`simulate-command`.
+
+Marking a word for the index is simple; use the index role.
+:index:`cross-reference`.

usersguide-sphinx/readme/conf.py

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+#
+# OpenModelica User's Guide documentation build configuration file, created by
+# sphinx-quickstart on Wed Jun  3 06:49:07 2015.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+import shlex
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+sys.path.append(os.path.abspath('.')) # For myext
+extensions = [
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.pngmath',
+    'sphinx.ext.ifconfig',
+    'sphinxcontrib.inlinesyntaxhighlight',
+    'sphinxcontribopenmodelica'
+]
+
+# As long as we are not generating with the epub tag it is save to use MathJax.
+if 'nomathjax' not in tags: extensions.append('sphinx.ext.mathjax')
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'How to Edit the OpenModelica User\'s Guide'
+copyright = u'2015, Open Source Modelica Consortium'
+author = u'Open Source Modelica Consortium'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.9.3'
+# The full version, including alpha/beta/rc tags.
+release = '1.9.3-dev'
+
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['source']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output ----------------------------------------------
+
+import alabaster
+html_theme_path = [alabaster.get_path()]
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+numfig = True
+numfig_format = {'figure': "Figure %s", 'table': "Table %s", 'code-block': "Listing %s"}
+
+highlight_language = 'modelica'

usersguide-sphinx/readme/index.rst

@@ -0,0 +1,10 @@
+.. toctree::
+  :maxdepth: 2
+
+  README
+  README.2
+
+Indices and tables
+------------------
+* :ref:`genindex`
+* :ref:`search`

usersguide-sphinx/source/conf.py

@@ -374,3 +374,5 @@
 
 numfig = True
 numfig_format = {'figure': "Figure %s", 'table': "Table %s", 'code-block': "Listing %s"}
+
+highlight_language = 'modelica'