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
==============
# -*- coding: utf-8 -*-
####################################################################################################
#
# PythonicGCodeMachine - @licence_header_description@
# Copyright (C) 2018 Fabrice Salvaire
#
####################################################################################################
####################################################################################################
#
# PythonicGCodeMachine documentation build configuration file, created by
# sphinx-quickstart on Fri Apr 8 16:54:03 2018.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
#
####################################################################################################
####################################################################################################
import sys, os
from datetime import datetime
# http://www.sphinx-doc.org/en/stable/extdev/logging.html
# from sphinx.util import logging
import logging
logger = logging.getLogger(__name__)
# try:
# import sphinx_rtd_theme
# except:
# logger.warning('Failed to import sphinx_rtd_theme')
# pass
####################################################################################################
# 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
# documentation root, use os.path.abspath to make it absolute, like shown here.
# for directory in ,:
PythonicGCodeMachine_path = os.path.abspath(os.path.join(__file__, *['..']*4))
sys.path.insert(0, PythonicGCodeMachine_path)
####################################################################################################
exec(compile(open(os.path.join(PythonicGCodeMachine_path, 'setup_data.py')).read(), 'setup_data.py', 'exec'))
####################################################################################################
#
# General configuration
#
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
# 'sphinx.ext.pngmath',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
'sphinxcontrib.getthecode',
'sphinx_sitemap',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'PythonicGCodeMachine'
copyright = '{0.year}, Fabrice Salvaire'.format(datetime.now())
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The full version, including alpha/beta/rc tags.
release = setup_dict['version']
# The short X.Y version.
version = '.'.join(release.split('.')[:2])
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
####################################################################################################
#
# Options for Autodoc
#
# Show both class-level docstring and __init__ docstring in class documentation
autoclass_content = 'both'
autodoc_default_flags = [
'members',
'undoc-members',
# 'private-members',
# 'special-members',
# 'inherited-members',
# 'show-inheritance',
]
####################################################################################################
#
# Options for HTML output
#
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#html_theme = 'PythonicGCodeMachine'
html_theme = 'PythonicGCodeMachineRtd'
# html_theme = 'sphinx_rtd_theme'
# on_rtd is whether we are on readthedocs.org
## on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
## if not on_rtd: # only import and set the theme if we're building docs locally
## import sphinx_rtd_theme
## html_theme = 'sphinx_rtd_theme'
## html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# otherwise, readthedocs.org uses their theme by default, so no need to specify it
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ['themes']
# html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
# html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'PythonicGCodeMachine'
####################################################################################################
#
# Options for LaTeX output
#
# The paper size ('letter' or 'a4').
# WARNING: latex_paper_size is deprecated. Use latex_elements['papersize'] instead.
# Fixme: don't work ???
latex_paper_size = 'a4'
# The font size ('10pt', '11pt' or '12pt').
latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'PythonicGCodeMachine.tex', 'PythonicGCodeMachine Documentation', 'Fabrice Salvaire', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Additional stuff for the LaTeX preamble.
# latex_preamble = ''
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
####################################################################################################
#
# Options for manual page output
#
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'PythonicGCodeMachine', 'PythonicGCodeMachine Documentation', ['Fabrice Salvaire'], 1)
]
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'http://docs.python.org/': None}
####################################################################################################
#
# MathJax
#
# Don't work
# mathjax_path = 'MathJax/MathJax.js'
####################################################################################################
#
# sphinx-sitemap
# https://github.com/jdillard/sphinx-sitemap
#
site_url = '@project_url@' # could use setup_dict
.. _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`
==================