Merge pull request #251 from cellml/cellml-2-drafting

Merge cellml-2-drafting into master

.gitignore

@@ -0,0 +1,5 @@
+.vscode/
+.DS_Store
+build/
+venv/
+venv_specification/

Makefile

@@ -10,7 +10,7 @@ BUILDDIR      = build
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) src
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 

README.rst

@@ -0,0 +1,106 @@
+
+CellML Specification
+====================
+
+This repository will be used by the CellML editors to develop the CellML specification (starting with the discontinued version 1.2)
+The content has been reworked to include an informal guide embedded within the normative specification text (in version 2.0).
+
+If things work correctly, changes in this repository will be reflected over at: https://cellml-specification.readthedocs.org/.
+
+Building the documentation locally
+----------------------------------
+
+The documentation can be built on your local machine with the following instructions.
+Do take note that the following instructions are suitable for Unix-derived operating systems and may need modification for other operating systems.
+Also, note that we require at least version 3.5 of Python to build the documentation.
+
+First clone a local copy of the CellML specification repository::
+
+  git clone https://github.com/cellml/cellml-specification.git
+
+Next setup a virtual environment::
+
+  virtualenv venv_specification
+
+**Note:** make sure you are creating virtual environment using a suitable Python interpreter, if required use the ``-p`` flag to set the Python interpreter (for example ``virtualenv -p /absolute/path/to/python venv_specification``).
+
+Then activate the virtual environment and instal the required packages::
+
+  source venv_specification/bin/activate
+  pip install -r cellml-specification/requirements.txt
+
+That completes the environment setup required for building the documentation.
+Once the environment is completed, the HTML form of the documentation can be built with the following commands::
+
+  cd cellml-specification
+  make html
+
+The built documentation will be available at::
+
+  /absolute/path/to/cellml-specification/build/html/index.html
+
+Any good internet browser will be able to display the documentation (see also `Serving the documentation`_).
+
+To build the documentation into a single page HTML document execute the following command::
+
+  make singlehtml
+
+The built documentation will be available at::
+
+  /absolute/path/to/cellml-specification/build/singlehtml/index.html
+
+Building PDFs
+^^^^^^^^^^^^^
+
+To build the PDF form of the documentation, simply execute the following command::
+
+  make latexpdf
+
+If this fails, please have a look at the following:
+
+Creating the PDF form of the documentation requires that some or all of a tool like Windows/`MikTeX <https://miktex.org/>`_, Windows/`TeXlive <https://www.tug.org/texlive/>`_, Linux/`TeXlive <https://www.tug.org/texlive/>`_, and macOS/`MacTeX <https://tug.org/mactex/>`_ is available to the Sphinx build tool.
+
+In addition, you'll need the following LaTeX packages: ``babel-greek``, ``capt-of``, ``cbfonts``, ``courier``, ``fncychap``, ``fontspec``, ``framed``, ``greek-fontenc``, ``helvetic``, ``latexmk``, ``needspace``, ``tabulary``, ``textgreek``, ``titlesec``, ``tocloft``, ``varwidth``, and ``wrapfig``.
+
+In particular, check that you have ``latexmk`` available as this is required for creating the PDF form of the documentation.
+Information on ``latexmk`` can be found at https://ctan.org/pkg/latexmk/.
+
+You may also need to install the `"GNU FreeFont" fonts <https://www.gnu.org/software/freefont/>`_ ``FreeSans``, ``FreeSerif``, and ``FreeMono``.
+
+Documentation builds
+^^^^^^^^^^^^^^^^^^^^
+
+There are two types of build that can be created from this codebase, they can be selected through the use of the environment variable ``CELLML_SPEC_BUILD``.
+
+1. Normative only, set ``CELLML_SPEC_BUILD=Normative`` (default build).
+2. Normative and informative specification combined, set ``CELLML_SPEC_BUILD=Full``
+
+Serving the documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can serve the documentation locally using a simple Python server.
+Save the following text to a file named ``webserver.py`` (this file can be saved anywhere on your harddrive)::
+
+  #!/usr/bin/env python
+
+  import http.server
+  import socketserver
+
+  PORT = 8008
+  Handler = http.server.SimpleHTTPRequestHandler
+
+  with socketserver.TCPServer(("", PORT), Handler) as httpd:
+      print("Serving at port", PORT)
+      httpd.serve_forever()
+
+To run the web server, use a terminal type application and change directory into::
+
+  cd /absolute/path/to/cellml-specification/build/html/
+
+then run the command::
+
+  python /absolute/path/to/webserver.py
+
+Now launch your internet browser and open the location::
+
+  http://localhost:8008/

requirements.txt

@@ -0,0 +1,3 @@
+sphinx>2,<3
+sphinx-hoverxref
+sphinx_rtd_theme