Commit ee16292e authored by Fabrice Salvaire's avatar Fabrice Salvaire

added doc template

parent 1b363c81
# -*- Makefile -*-
# Makefile for Sphinx documentation
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
CLIENTSOPTS = -D master_doc=contents-client
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
-rm -rf $(BUILDDIR)/*
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html-client."
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
@echo "Build finished; now you can process the pickle files."
@echo "Build finished; now you can process the JSON files."
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/GVLab.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GVLab.qhc"
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/GVLab"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/GVLab"
@echo "# devhelp"
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
@echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
@echo "Build finished. The text files are in $(BUILDDIR)/text."
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
@echo "The overview file is in $(BUILDDIR)/changes."
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
#! /bin/bash
make -f Makefile.sphinx html
#! /bin/bash
options="--export-area-page --export-background=white --export-background-opacity=0"
# --export-width=
for i in 1 2; do
inkscape --export-png=logo-v$i.png ${options} --export-height=${height} svg/logo-v$i.svg
inkscape --export-png=logo-v$i.png ${options} --export-height=${height} svg/logo-v$i.svg
.. -*- Mode: rst -*-
.. |Python| replace:: Python
.. _Python:
.. |PyPI| replace:: PyPI
.. _PyPI:
.. |Numpy| replace:: Numpy
.. _Numpy:
.. |IPython| replace:: IPython
.. _IPython:
.. |Sphinx| replace:: Sphinx
.. _Sphinx:
.. _bibliography-page:
This diff is collapsed.
.. _design-note-page:
Design Notes
To be written ...
.. _development-page:
Development & Community
PythonicGCodeMachine is an open-source project, and relies on its community of users to keep getting better.
PythonicGCodeMachine source code and issues are managed on `Github <>`_.
**Note to Packagers: Please don't create PythonicGCodeMachine package (PiPY do the job)**
How you can help ?
As an open source project, anyone is welcome to contribute in whatever form they are able.
.. , which can include taking part in discussions, filing bug reports, proposing improvements,
contributing code or documentation, and testing it.
* Promote PythonicGCodeMachine on the web and all around you
* Fill bug reports
* Test PythonicGCodeMachine on Linux, Windows and OS X
* Check for errors on the documentation
* Propose improvements
* Implement missing features
* Provides additional examples
The list of contributors is available at
.. _donate-page:
How to Help Further ?
If you like PythonicGCodeMachine, you can donate for its developement to my `PayPal account
This budget could help me to mainly finance a domain, a vps to host a site, a forum (*) and also to
participate to conference on open source Electronic Design Automation.
(*) This web site is actually hosted on my vps, which is quite loaded. I don't use hosting site
since it is easier to update the documentation using my own infrastructure.
.. include:: project-links.txt
.. include:: abbreviation.txt
.. _user-faq-page:
User FAQ
How to get help or report an issue ?
.. There is no mailing list or forum actually, so you can either contact me or fill an issue on Github.
If you want to **discuss or ask questions on PythonicGCodeMachine**, you can subscribe and post messages on the
**PythonicGCodeMachine User** mailing list.
There is actually three lists running on Google Groups (*):
`User List <!forum/PythonicGCodeMachine-user>`_
List for PythonicGCodeMachine users
`Announce List <!forum/PythonicGCodeMachine-announce>`_
List for announcements regarding PythonicGCodeMachine releases and development
`Devel List <!forum/PythonicGCodeMachine-devel>`_
List for developers of PythonicGCodeMachine
**If you encounter an issue, please fill an issue** on the `Issue Tracker <>`_.
(*) Despite Google Groups has many drawbacks, I don't have actually enough resources to run GNU Mailman or
Discourse on my own IT infrastructure.
.. _how-to-refer-page:
How to Refer to PythonicGCodeMachine ?
Up to now, the official url for PythonicGCodeMachine is @project_url@
*A permanent redirection will be implemented if the domain change in the future.*
On Github, you can use the **PythonicGCodeMachine** `topic <>`_ for repository related to PythonicGCodeMachine.
A typical `BibTeX <>`_ citation would be, for example:
.. code:: bibtex
author = {Fabrice Salvaire}, % actual author and maintainer
title = {PythonicGCodeMachine},
url = {@project_url@},
version = {x.y},
date = {yyyy-mm-dd}, % set to the release date
author = {Fabrice Salvaire},
title = {PythonicGCodeMachine},
howpublished = {\url{@project_url@}},
year = {yyyy}
.. include:: abbreviation.txt
.. include:: project-links.txt
.. raw:: html
.small-text {font-size: smaller}
.spacer {height: 30px}
.reduced-width {
max-width: 800px
.row {clear: both}
@media only screen and (min-width: 1000px),
only screen and (min-width: 500px) and (max-width: 768px){
.column {
padding-left: 5px;
padding-right: 5px;
float: left;
.column2 {
width: 50%;
.column3 {
width: 33.3%;
.. raw:: html
<div class="reduced-width">
.. image:: /_static/logo.png
:alt: PythonicGCodeMachine logo
:width: 750
.. important::
This doc was generated from a template and need to be completed ...
PythonicGCodeMachine is a free and open source (*) Python module which interface |Python|_ ...
.. rst-class:: small-text
(*) PythonicGCodeMachine is licensed under GPLv3 therms.
PythonicGCodeMachine requires Python 3 and works on Linux, Windows and OS X.
:ref:`To read more on PythonicGCodeMachine <overview-page>`
.. raw:: html
<div class="spacer"></div>
.. rst-class:: clearfix row
.. rst-class:: column column2
What's changed in versions
.. rst-class:: column column2
How to install PythonicGCodeMachine on your system
.. rst-class:: column column2
Answers to frequent questions
.. rst-class:: column column2
Many examples to learn how to use PythonicGCodeMachine.
.. rst-class:: column column2
How to contribute to the project
.. rst-class:: column column2
Technical reference material, for classes, methods, APIs, commands.
.. rst-class:: column column2
Guidelines to cite PythonicGCodeMachine
.. rst-class:: column column2
If you want to donate to the project or need a more professional support.
.. raw:: html
.. why here ???
.. rst-class:: clearfix row
.. raw:: html
<div class="spacer"></div>
Table of Contents
.. toctree::
:maxdepth: 3
.. include:: project-links.txt
.. include:: abbreviation.txt
.. _installation-page:
**Note to Packagers: Please don't create PythonicGCodeMachine package (PiPY do the job)**
On Windows
Firstly, you have to install the `Anaconda Distribution <>`_ so
as to get a full featured Python 3 environment.
Then open the `Anaconda Navigator <>`_ and launch a console for your root environment.
You can now run *pip* to install PythonicGCodeMachine in your root environment using this command:
.. code-block:: sh
pip install PythonicGCodeMachine
On Linux
Firstly, you have to install Python 3 from your distribution.
Then you can install PythonicGCodeMachine using *pip* or from source. See supra.
There are several ways to get Python on OSX:
* use the built in Python
* install `Miniconda <>`_
* install the `Anaconda Distribution <>`_.
* install from Brew `brew install python3` **(reported to work)**
You can install PythonicGCodeMachine using *pip* or from source. See supra.
Installation from PyPi Repository
PythonicGCodeMachine is available on the Python Packages |Pypi|_ repository at |PythonicGCodeMachine@pypi|
Run this command in the console to install the latest release:
.. code-block:: sh
pip install PythonicGCodeMachine
Install a more recent version from Github
If you want to install a version which is not yet released on Pypi, you can use one of theses
commands to install the stable or devel branch:
.. code-block:: sh
pip install git+
pip install git+
Installation from Source
The PythonicGCodeMachine source code is hosted at |PythonicGCodeMachine@github|
.. add link to pages ...
You have to solution to get the source code, the first one is to clone the repository, but if you
are not familiar with Git then you can simply download an archive either from the PythonicGCodeMachine Pypi page
(at the bottom) or the GitHub page (see clone or download button).
To clone the Git repository, run this command in a console:
.. code-block:: sh
git clone
Then to build and install PythonicGCodeMachine run these commands:
.. code-block:: sh
python build
python install
PythonicGCodeMachine requires the following dependencies:
* |Python|_ 3
* |Numpy|_
Also it is recommanded to have these Python modules:
* |IPython|_
.. * pip
.. * virtualenv
To generate the documentation, you will need in addition:
* |Sphinx|_
.. _news-page:
.. include:: news.txt
.. -*- Mode: rst -*-
.. include:: abbreviation.txt
.. include:: project-links.txt
.. no title here
V0 2018-01-01
Started project
.. include:: abbreviation.txt
.. include:: project-links.txt
.. _overview-page:
What is PythonicGCodeMachine ?
PythonicGCodeMachine is an open source Python module which provides a |Python|_ ....
How is PythonicGCodeMachine licensed ?
PythonicGCodeMachine is licensed under the `GPLv3 <>`_.
Going further with PythonicGCodeMachine
The best way to know what you can do with PythonicGCodeMachine, and to learn it, is to look at the examples:
* :ref:`PythonicGCodeMachine Reference Manual <reference-manual-page>`
* :ref:`Bibliography <bibliography-page>`
Which platforms are supported by PythonicGCodeMachine ?
PythonicGCodeMachine runs on Linux, Windows 64-bit and Mac OS X.
How to install PythonicGCodeMachine ?
The procedure to install PythonicGCodeMachine is described in the :ref:`Installation Manual <installation-page>`.
Which version of Python is required ?
PythonicGCodeMachine requires Python 3 and the version 3.5 is recommended so as to benefit from the new *@* syntax
for units.
.. -*- Mode: rst -*-
.. |ohloh| image::
:alt: Fabrice Salvaire's Ohloh profile
:height: 15px
:width: 80px
.. |PythonicGCodeMachineUrl| replace:: @project_url@
.. |PythonicGCodeMachineHomePage| replace:: PythonicGCodeMachine Home Page
.. _PythonicGCodeMachineHomePage: @project_url@
.. |PythonicGCodeMachine@readthedocs-badge| image::
.. |PythonicGCodeMachine@github| replace::
.. .. _PythonicGCodeMachine@github:
.. |PythonicGCodeMachine@pypi| replace::
.. .. _PythonicGCodeMachine@pypi:
.. |Build Status| image::
:alt: PythonicGCodeMachine build status
.. |Pypi Version| image::
:alt: PythonicGCodeMachine last version
.. |Pypi License| image::
:alt: PythonicGCodeMachine license
.. |Pypi Python Version| image::
:alt: PythonicGCodeMachine python version
.. coverage test
.. include:: abbreviation.txt
.. _reference-manual-page:
API Documentation
This is the API documentation for the PythonicGCodeMachine library.
.. warning:: The API documentation is automatically generated from the docstrings in the source
using the |Sphinx| tool. This way to produce the documentation is know to be perfectible
actually, but not too bad.
.. toctree::
:maxdepth: 2
* :ref:`genindex`
* :ref:`modindex`
.. * :ref:`search`
.. _related-projects-page:
Related Projects
.. _roadmap-page:
.. include:: abbreviation.txt
.. include:: project-links.txt
`Roadmap @Github <>`_
{%- extends "sphinx_rtd_theme/layout.html" %}
{% set script_files = script_files + ['_static/getthecode.js'] %}
{%- block extrahead %}
<link rel="stylesheet" type="text/css" href="" />
<script src=""></script>