First working version - autogenerated with sphinx

jmbarbier · Oct 14, 2013 · be2eb91 · be2eb91
1 parent fa453ab
commit be2eb91
Show file tree

Hide file tree

Showing 16 changed files with 786 additions and 259 deletions.
diff --git a/Makefile b/Makefile
@@ -77,17 +77,17 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/rstlit.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/rst2code.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/rstlit.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/rst2code.qhc"
 
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/rstlit"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/rstlit"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/rst2code"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/rst2code"
 	@echo "# devhelp"
 
 epub:

diff --git a/conf.py b/conf.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# rstlit documentation build configuration file, created by
+# rst2code documentation build configuration file, created by
 # sphinx-quickstart on Sat Oct 12 23:22:07 2013.
 #
 # This file is execfile()d with the current directory set to its containing dir.
@@ -40,7 +40,7 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'rstlit'
+project = u'rst2code'
 copyright = u'2013, BARBIER Jean-Matthieu'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -164,7 +164,7 @@
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'rstlitdoc'
+htmlhelp_basename = 'rst2codedoc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -183,7 +183,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'rstlit.tex', u'rstlit Documentation',
+  ('index', 'rst2code.tex', u'rst2code Documentation',
    u'BARBIER Jean-Matthieu', 'manual'),
 ]
 
@@ -213,7 +213,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'rstlit', u'rstlit Documentation',
+    ('index', 'rst2code', u'rst2code Documentation',
      [u'BARBIER Jean-Matthieu'], 1)
 ]
 
@@ -227,8 +227,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'rstlit', u'rstlit Documentation',
-   u'BARBIER Jean-Matthieu', 'rstlit', 'One line description of project.',
+  ('index', 'rst2code', u'rst2code Documentation',
+   u'BARBIER Jean-Matthieu', 'rst2code', 'One line description of project.',
    'Miscellaneous'),
 ]
 
@@ -245,7 +245,7 @@
 # -- Options for Epub output ---------------------------------------------------
 
 # Bibliographic Dublin Core info.
-epub_title = u'rstlit'
+epub_title = u'rst2code'
 epub_author = u'BARBIER Jean-Matthieu'
 epub_publisher = u'BARBIER Jean-Matthieu'
 epub_copyright = u'2013, BARBIER Jean-Matthieu'

diff --git a/index.rst b/index.rst
@@ -1,50 +1,68 @@
-.. rstlit documentation master file, created by
-   sphinx-quickstart on Sat Oct 12 23:22:07 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+Welcome to rst2code's documentation!
+====================================
 
-Welcome to rstlit's documentation!
-==================================
 
-**rstlit** est un outil de programmation littérale que je vais essayer
-de créer pour répondre à un besoin que j'ai depuis des années et que
-je n'ai pas pu combler en utilisant les outils existants.
+**rst2code** is a literate programming tool.
 
-Le principe
------------
+The goal
+--------
 
-Le principe est d'écrire le code en même temps que la documentation,
-et plus précisément de pouvoir générer le code à partir de la
-documentation. Contrairement aux outils permettant de générer la
-documentation à partir du code (docco, doxygen), ici l'idée est de
-générer le code à partir de la documentation.
+The goal is to be able to write code at the same time that documentation. More precisely, **rst2code** allows to
+generate code from documentation, whereas many tools - pycco, docco, doxygen, sphinx, are designed to extract
+documentation from code.
 
-L'ordre de lecture et de compréhension d'un humain n'étant pas
-forcément celui d'un ordinateur, la documentation doit pouvoir
-présenter les morceaux de codes dans un ordre différent de celui du
-code pour l'ordinateur.
+As human reading and understanding order is not the same than computer's, **rst2code** allows us to write code
+in any order, reassembling code blocks at "compile" time to obtain real source code suitable for computer use.
 
-La documentation doit pouvoir être utilisable directement, sans avoir
-à être transformée. Le code, en revanche, est généré par lecture de la
-documentation.
+**rst2code** is code agnostic (normally.. i tried it with python, html and coffee-script for now)
 
-L'outil doit être multi-languages.
+For the sake of readability, code blocks included in documentation should be easily syntax highligted (this means that
+a code block should be more or less valid code)
+
+
+Syntax
+------
+
+
+Code blocks are written in ... well, reStructuredText code blocks directives ( code / code-block / sourcecode / :: )
+
+Each code block is named, using code block name options (if available), or within a comment in the first line of
+code block. Names are in @@MACRONAME@@ form (characters surrounded by two @) :
 
-Les morceaux de code générés doivent pouvoir être valide avec un
-"surligneur de syntaxe" directement.
 
-Proposition de syntaxe
 
 .. code-block:: rest
 
   .. code-block:: langage
 
-     #MACRONAME definition
-     Code with #@@MACRONAME2@@ in comments
+     #@@MACRONAME@@ (within language comment)
+     Code
+
+or
+
+.. code-block:: rest
+
+  .. code:: language
+    :name: @@MACRONAME@@
+
+    Code
+
+or
+
+.. code-block:: rest
+
+  ::
+
+    @@MACRONAME@@ (within language comment)
+
+
+If **name** option is available, it is used to get block comment name.
+
+If not, or if no block name is found in **name** option, the first line of source code should
+contain the name inside a comment (language dependant), using the format @@MACRONAME@@.
+
+If no block name is found, the block is not used in **rst2code**
 
-If the first line of source code is a comment (language dependant)
-containing the special (unescaped) syntax @@MACRONAME@@, the code
-block have to be considered by the program generator.
 
 MACRONAMES definitions are :
 
@@ -58,49 +76,33 @@ MACRONAMES definitions are :
   moment.
 
 
-Inside the program lines, we detect comments containing @@MACRONAMES@@
+Inside the code blocks, **rst2code** detect comments containing @@MACRONAMES@@
 strings, remove the comment while retaining indentation for every line
-in macro content and then replace it. Circular references have to be
-detected.
-
-L'invocation du code est faite par la ligne de commande suivante ::
+in macro content and then replace it.
 
-  $ rst2code [OPTIONS] DEST_DIR RST_FILE1 RST_FILE2 RST_FILE3 ...
+Usage
+-----
 
-Le programme se compose donc de la manière suivante ::
+With "standard" reStructuredText ::
 
-  #@@/rst2code.py@@
-
-  #@@python headers@@
-  #@@license@@
-  #@@imports@@
-  if __main__:
-              #@@main_function@@
-  #@@command line arguments@@
-  #@@rst file parser@@
-  #@@blocks analysis@@
-  #@@code generator@@
-
-
-
-La license du programme est la license GPLv3 ::
+  $ rst2code [OPTIONS] DEST_DIR RST_FILE1 RST_FILE2 RST_FILE3 ...
 
-  #@@license@@
-  # GPL v3
 
-La fonction principale ::
+With "sphinx-flavoured" .rst files : just add "rst2code" to sphinx extensions, and
+set rst2code_output_dir config option and launch any sphinx document generation.
 
-  #@@main_function@@
-  def main():
-    return True
+**Current rst2code module have been written from this documentation**
 
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-
+   source/index
+   source/cmdline
+   source/sphinx
+   source/misc
 
 Indices and tables
 ==================

diff --git a/make.bat b/make.bat
@@ -99,9 +99,9 @@ if "%1" == "qthelp" (
 	echo.
 	echo.Build finished; now you can run "qcollectiongenerator" with the ^
 .qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\rstlit.qhcp
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\rst2code.qhcp
 	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\rstlit.ghc
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\rst2code.ghc
 	goto end
 )
 

diff --git a/parser/generate.py b/parser/generate.py
diff --git a/parser/index.rst b/parser/index.rst
diff --git a/parser/process.py b/parser/process.py
diff --git a/parser/store.py b/parser/store.py
diff --git a/parser/test.py b/parser/test.py