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.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
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
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
help:
@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)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
htmlclient:
$(SPHINXBUILD) -b html $(CLIENTSOPTS) $(ALLSPHINXOPTS) $(BUILDDIR)/html-client
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html-client."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@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"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@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"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@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)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@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=
height=400
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
done
.. -*- Mode: rst -*-
.. |Python| replace:: Python
.. _Python: http://python.org
.. |PyPI| replace:: PyPI
.. _PyPI: https://pypi.python.org/pypi
.. |Numpy| replace:: Numpy
.. _Numpy: http://www.numpy.org
.. |IPython| replace:: IPython
.. _IPython: http://ipython.org
.. |Sphinx| replace:: Sphinx
.. _Sphinx: http://sphinx-doc.org
.. _bibliography-page:
==============
Bibliography
==============
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 <https://github.com/FabriceSalvaire/PythonicGCodeMachine>`_.
**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
Contributors
------------
The list of contributors is available at https://github.com/FabriceSalvaire/PythonicGCodeMachine/graphs/contributors
.. _donate-page:
=======================
How to Help Further ?
=======================
If you like PythonicGCodeMachine, you can donate for its developement to my `PayPal account
<https://www.paypal.me/FabriceSalvaire>`_.
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 <https://groups.google.com/forum/#!forum/PythonicGCodeMachine-user>`_
List for PythonicGCodeMachine users
`Announce List <https://groups.google.com/forum/#!forum/PythonicGCodeMachine-announce>`_
List for announcements regarding PythonicGCodeMachine releases and development
`Devel List <https://groups.google.com/forum/#!forum/PythonicGCodeMachine-devel>`_
List for developers of PythonicGCodeMachine
**If you encounter an issue, please fill an issue** on the `Issue Tracker <https://github.com/FabriceSalvaire/PythonicGCodeMachine/issues>`_.
(*) 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 <https://github.com/search?q=topic%3APythonicGCodeMachine&type=Repositories>`_ for repository related to PythonicGCodeMachine.
A typical `BibTeX <https://en.wikipedia.org/wiki/BibTeX>`_ citation would be, for example:
.. code:: bibtex
@software{PythonicGCodeMachine,
author = {Fabrice Salvaire}, % actual author and maintainer
title = {PythonicGCodeMachine},
url = {@project_url@},
version = {x.y},
date = {yyyy-mm-dd}, % set to the release date
}
@Misc{PythonicGCodeMachine,
author = {Fabrice Salvaire},
title = {PythonicGCodeMachine},
howpublished = {\url{@project_url@}},
year = {yyyy}
}
.. include:: abbreviation.txt
.. include:: project-links.txt
.. raw:: html
<style>
.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%;
}
}
</style>
.. raw:: html
<div class="reduced-width">
########
Title
########
.. image:: /_static/logo.png
:alt: PythonicGCodeMachine logo
:width: 750
.. important::
This doc was generated from a template and need to be completed ...
********
Overview
********
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
:ref:`news-page`
================
What's changed in versions
.. rst-class:: column column2
:ref:`Installation-page`
========================
How to install PythonicGCodeMachine on your system
.. rst-class:: column column2
:ref:`user-faq-page`
====================
Answers to frequent questions
.. rst-class:: column column2
:ref:`examples-page`
====================
Many examples to learn how to use PythonicGCodeMachine.
.. rst-class:: column column2
:ref:`development-page`
=======================
How to contribute to the project
.. rst-class:: column column2
:ref:`reference-manual-page`
============================
Technical reference material, for classes, methods, APIs, commands.
.. rst-class:: column column2
:ref:`how-to-refer-page`
========================
Guidelines to cite PythonicGCodeMachine
.. rst-class:: column column2
:ref:`donate-page`
==================
If you want to donate to the project or need a more professional support.
.. raw:: html
</div>
.. why here ???
.. rst-class:: clearfix row
.. raw:: html
<div class="spacer"></div>
*******************
Table of Contents
*******************
.. toctree::
:maxdepth: 3
:numbered:
overview.rst
news.rst
roadmap.rst
installation.rst
faq.rst
design-notes.rst
reference-manual.rst
development.rst
how-to-refer.rst
donate.rst
related-projects.rst
bibliography.rst
.. include:: project-links.txt
.. include:: abbreviation.txt
.. _installation-page:
==============
Installation
==============
**Note to Packagers: Please don't create PythonicGCodeMachine package (PiPY do the job)**
On Windows
----------
Firstly, you have to install the `Anaconda Distribution <https://www.anaconda.com/download/>`_ so
as to get a full featured Python 3 environment.
Then open the `Anaconda Navigator <https://docs.continuum.io/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.
On OSX
------
There are several ways to get Python on OSX:
* use the built in Python
* install `Miniconda <https://conda.io/miniconda.html>`_
* install the `Anaconda Distribution <https://www.anaconda.com/download/>`_.
* 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+https://github.com/FabriceSalvaire/PythonicGCodeMachine
pip install git+https://github.com/FabriceSalvaire/PythonicGCodeMachine@devel
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 https://github.com/FabriceSalvaire/PythonicGCodeMachine.git
Then to build and install PythonicGCodeMachine run these commands:
.. code-block:: sh
python setup.py build
python setup.py install
Dependencies
------------
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:
======
News
======
.. 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:
==========
Overview
==========
What is PythonicGCodeMachine ?
---------------------
PythonicGCodeMachine is an open source Python module which provides a |Python|_ ....
How is PythonicGCodeMachine licensed ?
-----------------------------
PythonicGCodeMachine is licensed under the `GPLv3 <https://www.gnu.org/licenses/quick-guide-gplv3.en.html>`_.
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 -*-
..
|PythonicGCodeMachineUrl|
|PythonicGCodeMachineHomePage|_
|PythonicGCodeMachineDoc|_
|PythonicGCodeMachine@github|_
|PythonicGCodeMachine@readthedocs|_
|PythonicGCodeMachine@readthedocs-badge|
|PythonicGCodeMachine@pypi|_
.. |ohloh| image:: https://www.openhub.net/accounts/230426/widgets/account_tiny.gif
:target: https://www.openhub.net/accounts/fabricesalvaire
: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:: https://readthedocs.org/projects/PythonicGCodeMachine/badge/?version=latest
:target: http://PythonicGCodeMachine.readthedocs.org/en/latest
.. |PythonicGCodeMachine@github| replace:: https://github.com/FabriceSalvaire/PythonicGCodeMachine
.. .. _PythonicGCodeMachine@github: https://github.com/FabriceSalvaire/PythonicGCodeMachine
.. |PythonicGCodeMachine@pypi| replace:: https://pypi.python.org/pypi/PythonicGCodeMachine
.. .. _PythonicGCodeMachine@pypi: https://pypi.python.org/pypi/PythonicGCodeMachine
.. |Build Status| image:: https://travis-ci.org/FabriceSalvaire/PythonicGCodeMachine.svg?branch=master
:target: https://travis-ci.org/FabriceSalvaire/PythonicGCodeMachine
:alt: PythonicGCodeMachine build status @travis-ci.org
.. |Pypi Version| image:: https://img.shields.io/pypi/v/PythonicGCodeMachine.svg
:target: https://pypi.python.org/pypi/PythonicGCodeMachine
:alt: PythonicGCodeMachine last version
.. |Pypi License| image:: https://img.shields.io/pypi/l/PythonicGCodeMachine.svg
:target: https://pypi.python.org/pypi/PythonicGCodeMachine
:alt: PythonicGCodeMachine license
.. |Pypi Python Version| image:: https://img.shields.io/pypi/pyversions/PythonicGCodeMachine.svg
:target: https://pypi.python.org/pypi/PythonicGCodeMachine
:alt: PythonicGCodeMachine python version
.. coverage test
.. https://img.shields.io/pypi/status/Django.svg
.. https://img.shields.io/github/stars/badges/shields.svg?style=social&label=Star
.. 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.
Contents:
.. toctree::
:maxdepth: 2
api/PythonicGCodeMachine
Indexes
-------
* :ref:`genindex`
* :ref:`modindex`
.. * :ref:`search`
.. _related-projects-page:
==================
Related Projects
==================
.. _roadmap-page:
.. include:: abbreviation.txt
.. include:: project-links.txt
=========
Roadmap
=========
`Roadmap @Github <https://github.com/FabriceSalvaire/PythonicGCodeMachine/milestones>`_
{%- extends "sphinx_rtd_theme/layout.html" %}
{% set script_files = script_files + ['_static/getthecode.js'] %}
{%- block extrahead %}
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/cookieconsent2/3.0.3/cookieconsent.min.css" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/cookieconsent2/3.0.3/cookieconsent.min.js"></script>
<script>
window.addEventListener("load", function(){
window.cookieconsent.initialise({
"palette": {
"popup": {
"background": "#000"
},
"button": {
"background": "#f1d600"
}