Merge pull request #57 from optimsoc/rstversion

doc: Automatically handle versions

doc/conf.py

@@ -14,6 +14,7 @@
 
 import sys
 import os
+import git
 
 # 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
@@ -64,10 +65,25 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = u'2017.1'
-# The full version, including alpha/beta/rc tags.
-release = u'2017.1'
+
+repo = git.repo.Repo(os.path.join(os.path.dirname(__file__), '..'))
+gitdescribe = repo.git.describe()
+lastversion = gitdescribe[1:7]
+if len(gitdescribe) > 7:
+    version = "dev-" + repo.git.rev_parse('--abbrev-ref', 'HEAD')
+    release = "development commit " + repo.git.rev_parse('HEAD')[0:11]
+else:
+    version = lastversion
+    release = lastversion
+
+rst_epilog = """
+.. |lastversion| replace:: {0}
+.. |dl_base| replace:: https://github.com/optimsoc/sources/releases/download/v{0}/optimsoc-{0}-base.tar.gz
+.. |dl_examples| replace:: https://github.com/optimsoc/sources/releases/download/v{0}/optimsoc-{0}-examples.tar.gz
+""".format(lastversion)
+
+def setup(app):
+    app.add_config_value('lastversion', '', 'env')
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/requirements.txt

@@ -1,2 +1,3 @@
 Sphinx
 breathe
+gitpython

doc/user_guide/installation.rst

@@ -87,29 +87,35 @@ The recommended default is to install OpTiMSoC into ``/opt/optimsoc``.
 There are two packages: the ``base`` package contains the programs, libraries and tools to get started.
 The ``examples`` package contains prebuilt example systems (both in simulation and FPGA bitstreams) for the real quick start.
 
-To install the 2016.1 release into ``/opt/optimsoc``, run the following commands:
+.. ifconfig:: lastversion != version
 
-.. code:: sh
+   .. note:: This documentation was generated for a development version and you cannot download prebuild packages for it.
+      Some parts of this documentation will vary from the release documentation and examples not work anymore.
+      Please refer to the documentation matching the last release that you can find here: https://optimsoc.org/docs.
+
+To install the |lastversion| release into ``/opt/optimsoc``, run the following commands:
+
+.. parsed-literal::
 
-   wget https://github.com/optimsoc/sources/releases/download/v2016.1/optimsoc-2016.1-base.tar.gz
-   wget https://github.com/optimsoc/sources/releases/download/v2016.1/optimsoc-2016.1-examples.tar.gz
-   tar -xf optimsoc-2016.1-base.tar.gz -C /opt/optimsoc
-   tar -xf optimsoc-2016.1-examples.tar.gz -C /opt/optimsoc
+   wget |dl_base|
+   wget |dl_examples|
+   tar -xf optimsoc-|lastversion|-base.tar.gz -C /opt/optimsoc
+   tar -xf optimsoc-|lastversion|-examples.tar.gz -C /opt/optimsoc
 
 To use OpTiMSoC multiple environment variables need to be set.
 This is done by running the following command **in every terminal session that you want to use OpTiMSoC in**:
 
-.. code:: sh
+.. parsed-literal::
 
-   cd /opt/optimsoc/2016.1
+   cd /opt/optimsoc/|lastversion|
    source optimsoc-environment.sh
 
 .. note:: Automatically load the OpTiMSoC environment in every new
    terminal session by adding it to your ``~/.bashrc`` file:
 
-   .. code:: sh
+   .. parsed-literal::
 
-      echo 'cd /opt/optimsoc/2016.1; source optimsoc-environment.sh' >> ~/.bashrc
+      echo 'cd /opt/optimsoc/|lastversion|; source optimsoc-environment.sh' >> ~/.bashrc
 
 Installation complete!
 
@@ -133,12 +139,12 @@ First, you need some additional tools (the "build dependencies"):
 
 Then get the sources from git:
 
-.. code:: sh
+.. parsed-literal::
 
    git clone https://github.com/optimsoc/sources.git optimsoc-sources
    cd optimsoc-sources
    # optional: checkout a release version
-   git checkout v2016.1
+   git checkout |lastversion|
 
 Now you're ready to build OpTiMSoC.