From 4381c08a0cc9a3fb38688802af9c90d049119c5d Mon Sep 17 00:00:00 2001 From: Erik Gren Date: Wed, 29 Jul 2020 08:31:40 +0200 Subject: [PATCH] Sphinx Documentation Initiation --- README.md | 2 +- docs/BEHIND_THE_SCENES.md | 8 -- docs/EXAMPLE.md | 49 --------- docs/LINUX.md | 1 - docs/MACOS.md | 1 - docs/Makefile | 19 ++++ docs/WINDOWS.md | 1 - docs/make.bat | 35 ++++++ docs/source/behind_the_scenes.rst | 16 +++ docs/source/conf.py | 175 ++++++++++++++++++++++++++++++ docs/source/index.rst | 28 +++++ examples/example_007.py | 2 +- 12 files changed, 275 insertions(+), 62 deletions(-) delete mode 100644 docs/BEHIND_THE_SCENES.md delete mode 100644 docs/EXAMPLE.md delete mode 100644 docs/LINUX.md delete mode 100644 docs/MACOS.md create mode 100644 docs/Makefile delete mode 100644 docs/WINDOWS.md create mode 100644 docs/make.bat create mode 100644 docs/source/behind_the_scenes.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/README.md b/README.md index 4922a2b..712542e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -[![Build Status](https://travis-ci.org/Canvim/PyPen.svg?branch=master)](https://travis-ci.org/Canvim/PyPen) [![PyPI - Version](https://img.shields.io/pypi/v/pypen.svg?logo=python&color=lightblue&label=Version)](https://pypi.org/project/pypen/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/pypen?color=lightgreen&label=Downloads&logo=pypi)](https://pypi.org/project/pypen/) [![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/Canvim/PyPen?color=purple&label=Size&logo=github)](https://github.com/Canvim/PyPen/) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/Canvim/PyPen/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/Canvim/PyPen/?branch=master) +[![Build Status](https://travis-ci.org/Canvim/PyPen.svg?branch=master)](https://travis-ci.org/Canvim/PyPen) [![PyPI - Version](https://img.shields.io/pypi/v/pypen.svg?logo=python&color=lightblue&label=Version)](https://pypi.org/project/pypen/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/pypen?color=lightgreen&label=Downloads&logo=pypi)](https://pypi.org/project/pypen/) [![Documentation Status](https://readthedocs.org/projects/pypen/badge/?version=latest)](https://pypen.readthedocs.io/en/latest/?badge=latest) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/Canvim/PyPen/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/Canvim/PyPen/?branch=master) Express your creativity in Python through simple PyPen sketches! diff --git a/docs/BEHIND_THE_SCENES.md b/docs/BEHIND_THE_SCENES.md deleted file mode 100644 index 0c7d436..0000000 --- a/docs/BEHIND_THE_SCENES.md +++ /dev/null @@ -1,8 +0,0 @@ -## [<- Back](https://github.com/Canvim/PyPen) - -## How does PyPen *Really* Work? -PyPen currently utilizes pygame in the background for event-management, draw-calls and window-management. In the future, we're considering making the switch to cairo (pycairo) to have a more robust, vector-based drawing-backend and perhaps a standard qtinker-window or maybe a pyglet one for event- and window-management. However, due to availability issues on windows with cairo and some failed attempts at drawing all primitives with OpenGL, we chose to use pygame in the meantime. - -When you call ```pypen ``` PyPen 'imports' your sketch, launces a pygame window, executes your start() function, and schedules the update() function according to the specified framerate. It then interprets and translates all your drawing functions and properly routes pygame events to easy functions exposed to you and plants useful variables such as ```DELTA_TIME```, ```WIDTH``` and more inside your sketch. - -This means that all the PyPen user ever has to worry about is the fun parts (though some might disagree with that assessment xP) of creating a sketch. \ No newline at end of file diff --git a/docs/EXAMPLE.md b/docs/EXAMPLE.md deleted file mode 100644 index 03aa97c..0000000 --- a/docs/EXAMPLE.md +++ /dev/null @@ -1,49 +0,0 @@ -## [<- Back](https://github.com/Canvim/PyPen) - -# How do I use PyPen? -## 1. Install PyPen -To install pypen, make sure you have Python 3.8 or higher installed as well as pip configured and available in your PATH. Once that's done, simply do **```pip install pypen```**. To verify that it was installed correctly, run **```pypen --version```** (or ```python -m pypen --version```) and it should display the current version of PyPen. - -Since Cairo - one of PyPen's dependencies - sometimes can be a bit tricky to install, see our OS-specific instructions available here: -* [Windows](./WINDOWS.md) -* [MacOS](./MACOS.md) -* [Linux](./LINUX.md) - -## 2. Create a PyPen Sketch -To create a basic sketch, just call **```pypen --init pypen_example.py```** (or whatever you want). This creates a file named 'pypen_example.py' (or whatever you provided the ```pypen --init``` with) which contains some PyPen code looking like this: - -```python -from pypen import * - - -def start(): - settings.fps = 60 - - -def update(): - fill("orange") - rectangle(20, 20, 300, 400, "red") -``` - -(You of course don't have to use pypen --init to create all your sketches, but it's very convenient) - -## 3. Run Your Sketch! -You can then run it by simply calling: -- **```pypen pypen_example.py```** -- (or ```python -m pypen pypen_example.py```) - -## 4. Profit! -If everything worked, a window should launch containing something looking like this: - - - -Wohoo! You made it! You have now launched your first PyPen sketch! Try changing some variables like the color from ```"red"``` to ```"blue"``` or the width and height of the rectangle (or maybe even change it into a circle!). - -## 5. What now? -There is much more that PyPen can do that you have yet to discover. Interested in seeing how simple it is to use PyPen? We have an entire folder filled with interesting PyPen examples spanning from very simple to some more advanced ones as well. You find them in the 'examples/' folder on our repository located here: - -## **[Examples](../examples/)** - -You can also refer to our documentation available here: - -## **[Documentation](../examples/)** \ No newline at end of file diff --git a/docs/LINUX.md b/docs/LINUX.md deleted file mode 100644 index 9c54e53..0000000 --- a/docs/LINUX.md +++ /dev/null @@ -1 +0,0 @@ -## [<- Back](./EXAMPLE.md) diff --git a/docs/MACOS.md b/docs/MACOS.md deleted file mode 100644 index 9c54e53..0000000 --- a/docs/MACOS.md +++ /dev/null @@ -1 +0,0 @@ -## [<- Back](./EXAMPLE.md) diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..69fe55e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md deleted file mode 100644 index 9c54e53..0000000 --- a/docs/WINDOWS.md +++ /dev/null @@ -1 +0,0 @@ -## [<- Back](./EXAMPLE.md) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..543c6b1 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/source/behind_the_scenes.rst b/docs/source/behind_the_scenes.rst new file mode 100644 index 0000000..07e757b --- /dev/null +++ b/docs/source/behind_the_scenes.rst @@ -0,0 +1,16 @@ +.. _behind the scenes: + +How does PyPen *Really* Work? +----------------------------- + +PyPen currently utilizes Pyglet in the background for event and window-management. For drawing, Cairo (through PyCairo) is used, making for a stable and quick svg drawing backend. + +When you call ``pypen `` PyPen 'imports' your sketch, +launces a Pyglet window, executes your start() function, and schedules +the update() function according to the specified framerate. It then +interprets and translates all your drawing functions and properly routes +Pyglet events to easy functions exposed to you and plants useful +variables such as ``DELTA_TIME``, ``WIDTH`` and more inside your sketch. + +This means that all the PyPen user ever has to worry about is the fun +parts of creating a sketch, rather than all the boilerplate code usually involved (though some might disagree with the assessment of what is the fun part here xP). diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..a7b139a --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,175 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# 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. + +# import os +# import sys +# sys.path.insert(0, os.path.abspath("../..")) + + +# -- Project information ----------------------------------------------------- + +project = 'PyPen' +copyright = '2020, ErikWDev, cqann' +author = 'ErikWDev, cqann' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '0.1.0' + + +# -- 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 = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- 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 = 'sphinx_rtd_theme' + +# 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 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 = ['resources'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PyPendoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'PyPen.tex', 'PyPen Documentation', + 'ErikWDev, cqann', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'pypen', 'PyPen Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'PyPen', 'PyPen Documentation', + author, 'PyPen', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..d371e65 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,28 @@ + +.. image :: ../../PyPen.svg + :width: 400 + :alt: PyPen Logo + +========================================== +Welcome to PyPen's official Documentation! +========================================== + +This is the official documentation for PyPen + +.. warning:: + + PyPen - and its documentation - is still under active development, meaning that breaking changes might be introduced at any time. + +.. toctree:: + :maxdepth: 3 + :caption: Contents: + + +Getting Started +=============== +- :ref:`test` + + +(*For Maintainers*) How does PyPen work? +======================================== +Are you interested in the inner workings of PyPen? Checkout the article :ref:`behind the scenes` diff --git a/examples/example_007.py b/examples/example_007.py index 1437afe..95a3d3e 100644 --- a/examples/example_007.py +++ b/examples/example_007.py @@ -53,8 +53,8 @@ def start(): def update(): - global current_x, current_y fill_screen("#343434") + for icon in icons: icon.update()