The CodeChat system for software documentation
Project description
.. Copyright (C) 2012-2015 Bryan A. Jones.
This file is part of CodeChat.
CodeChat is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
CodeChat is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with CodeChat. If not, see <http://www.gnu.org/licenses/>.
*****************************
A programmer's word processor
*****************************
`CodeChat <https://pythonhosted.org/CodeChat/README.html>`_ transforms source code into a web page, allowing developers to view their program as a beautiful and descriptive document by adding headings, formatting, hyperlinks, diagrams, images, and other forms of rich content to capture the ideas and insights that naturally flow from the process of writing a program. It also provides a blank slate in which to plan ahead, by sketching out an algorithm before committing it to code or laying out a design document which can evolve as the code does. This `literate programming <http://www.literateprogramming.com/>`_ paradigm changes the way developers think by intermingling ideas with their implementation as code, dramatically improving a programmer’s abilities.
.. Note that hyperlinks don't use the typical :doc: syntax here, because:
1. This same file will be processed by reST-only tools on the Bitbucket and PyPI pages, so :doc: will produce errors.
2. Pointing to the doc homepage causes Bitbucket and PyPI links to automatically refer users to the full documentation set, rather than the single file (this one) hosted automatically there.
.. The following includes a YouTube CodeChat playlist.
.. raw:: html
<iframe width="852" height="480" src="https://www.youtube.com/embed/ZEcWXR5maXE?list=PLOJAqFa3UI2EmpUOy7PhAJ7adRnBZkC6U" frameborder="0" allowfullscreen></iframe>
Background
==========
Put simply, literate programming (LP) is the realization that a program is a document written to and for fellow programmers, not simply a list of instructions for a computer. LP tools therefore produce a nicely-formatted document which contains the code intermixed with explanatory prose. `Donald Knuth <http://en.wikipedia.org/wiki/Donald_Knuth>`_ introducted literate programming using his WEB tool in his seminal `paper <http://www.literateprogramming.com/knuthweb.pdf>`_. Per Figure 1 of this paper_, the WEB system takes a ``.w`` document as input then produces either a "tangled" source file for compilation or a "woven" document as a ``.tex`` file. The document is beautiful; the WEB source is difficult to digest (see Figure 2a-c); the source code is completely unreadable (see Figure 3). While a plethora of `tools <http://en.wikipedia.org/wiki/Literate_programming#Tools>`_ developed over the years attempt to address these problems, only one `LP-inspired <http://rant.gulbrandsen.priv.no/udoc/history>`_ variant has gained widespread acceptance: documentation generators, such as `Doxygen <http://www.doxygen.org>`_ and `JavaDoc <http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html>`_, which extract documentation directly from source code, rather than extracting source code from the documentation, as WEB and most LP tools do. CodeChat addresses these LP weaknesses by producing a doucment directly from the code; employing human-readable markup (reStructuredText); and by supporting a GUI to make editing an LP document-program faster and easier.
Tutorial
========
The `tutorial <https://pythonhosted.org/CodeChat/tutorial.html>`_ guides new users into exploring CodeChat's literate programming abilities. Start here! Or, peruse the examples below to see the ways in which CodeChat transforms plain source code into beautiful documents.
.. _tutorial-examples:
Examples
========
Some examples of literate programming using CodeChat:
* Use of a ``toctree`` directive to categorize all source files in `CodeChat itself <https://pythonhosted.org/CodeChat/>`_
* Use of tables to help design a `simple parser <https://pythonhosted.org/CodeChat/CodeChat/CodeToRest.html#step-5-of-lexer-to-rest>`_.
* Use of a numbered list to explain a `simple state machine <https://pythonhosted.org/CodeChat/CodeChat/CodeToRest.html#summary-and-implementation>`_.
* Use of hyperlinks to provide reference information for all `Sphinx configuration values <https://pythonhosted.org/CodeChat/conf.html>`_.
* Use of fonts to show what ``setup.py`` `commands to run <https://pythonhosted.org/CodeChat/setup.html>`_
* Use of a screenshot to demonstrate the operation of a `3-D simulation <https://dl.dropboxusercontent.com/u/2337351/CodeChat_MAVs/homework_1_solution.html>`_.
* Use of equations and diagrams in `scientific computing <https://dl.dropboxusercontent.com/u/2337351/CodeChat_MAVs/mav3d_simulation.html#dynamics>`_.
* Use of equations to explain the resulting code for an `integrator <https://dl.dropboxusercontent.com/u/2337351/CodeChat_MAVs/integrating_omega_3d.html>`_.
* CodeChat is used for code examples in a course on `microprocessors <http://www.ece.msstate.edu/courses/ece3724/main_pic24/docs/sphinx/textbook_examples.html>`_.
Contributing
============
This is a fairly basic implementation; much improvement is needed! Please use the `issue tracker <http://bitbucket.org/bjones/documentation/issues?status=new&status=open>`_ to report bugs or request features; even better, contribute to the code at the CodeChat_ homepage!
License
=======
Copyright (C) 2012-2015 Bryan A. Jones.
This file is part of CodeChat.
CodeChat is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
CodeChat is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with CodeChat. If not, see <http://www.gnu.org/licenses/>.
This file is part of CodeChat.
CodeChat is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
CodeChat is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with CodeChat. If not, see <http://www.gnu.org/licenses/>.
*****************************
A programmer's word processor
*****************************
`CodeChat <https://pythonhosted.org/CodeChat/README.html>`_ transforms source code into a web page, allowing developers to view their program as a beautiful and descriptive document by adding headings, formatting, hyperlinks, diagrams, images, and other forms of rich content to capture the ideas and insights that naturally flow from the process of writing a program. It also provides a blank slate in which to plan ahead, by sketching out an algorithm before committing it to code or laying out a design document which can evolve as the code does. This `literate programming <http://www.literateprogramming.com/>`_ paradigm changes the way developers think by intermingling ideas with their implementation as code, dramatically improving a programmer’s abilities.
.. Note that hyperlinks don't use the typical :doc: syntax here, because:
1. This same file will be processed by reST-only tools on the Bitbucket and PyPI pages, so :doc: will produce errors.
2. Pointing to the doc homepage causes Bitbucket and PyPI links to automatically refer users to the full documentation set, rather than the single file (this one) hosted automatically there.
.. The following includes a YouTube CodeChat playlist.
.. raw:: html
<iframe width="852" height="480" src="https://www.youtube.com/embed/ZEcWXR5maXE?list=PLOJAqFa3UI2EmpUOy7PhAJ7adRnBZkC6U" frameborder="0" allowfullscreen></iframe>
Background
==========
Put simply, literate programming (LP) is the realization that a program is a document written to and for fellow programmers, not simply a list of instructions for a computer. LP tools therefore produce a nicely-formatted document which contains the code intermixed with explanatory prose. `Donald Knuth <http://en.wikipedia.org/wiki/Donald_Knuth>`_ introducted literate programming using his WEB tool in his seminal `paper <http://www.literateprogramming.com/knuthweb.pdf>`_. Per Figure 1 of this paper_, the WEB system takes a ``.w`` document as input then produces either a "tangled" source file for compilation or a "woven" document as a ``.tex`` file. The document is beautiful; the WEB source is difficult to digest (see Figure 2a-c); the source code is completely unreadable (see Figure 3). While a plethora of `tools <http://en.wikipedia.org/wiki/Literate_programming#Tools>`_ developed over the years attempt to address these problems, only one `LP-inspired <http://rant.gulbrandsen.priv.no/udoc/history>`_ variant has gained widespread acceptance: documentation generators, such as `Doxygen <http://www.doxygen.org>`_ and `JavaDoc <http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html>`_, which extract documentation directly from source code, rather than extracting source code from the documentation, as WEB and most LP tools do. CodeChat addresses these LP weaknesses by producing a doucment directly from the code; employing human-readable markup (reStructuredText); and by supporting a GUI to make editing an LP document-program faster and easier.
Tutorial
========
The `tutorial <https://pythonhosted.org/CodeChat/tutorial.html>`_ guides new users into exploring CodeChat's literate programming abilities. Start here! Or, peruse the examples below to see the ways in which CodeChat transforms plain source code into beautiful documents.
.. _tutorial-examples:
Examples
========
Some examples of literate programming using CodeChat:
* Use of a ``toctree`` directive to categorize all source files in `CodeChat itself <https://pythonhosted.org/CodeChat/>`_
* Use of tables to help design a `simple parser <https://pythonhosted.org/CodeChat/CodeChat/CodeToRest.html#step-5-of-lexer-to-rest>`_.
* Use of a numbered list to explain a `simple state machine <https://pythonhosted.org/CodeChat/CodeChat/CodeToRest.html#summary-and-implementation>`_.
* Use of hyperlinks to provide reference information for all `Sphinx configuration values <https://pythonhosted.org/CodeChat/conf.html>`_.
* Use of fonts to show what ``setup.py`` `commands to run <https://pythonhosted.org/CodeChat/setup.html>`_
* Use of a screenshot to demonstrate the operation of a `3-D simulation <https://dl.dropboxusercontent.com/u/2337351/CodeChat_MAVs/homework_1_solution.html>`_.
* Use of equations and diagrams in `scientific computing <https://dl.dropboxusercontent.com/u/2337351/CodeChat_MAVs/mav3d_simulation.html#dynamics>`_.
* Use of equations to explain the resulting code for an `integrator <https://dl.dropboxusercontent.com/u/2337351/CodeChat_MAVs/integrating_omega_3d.html>`_.
* CodeChat is used for code examples in a course on `microprocessors <http://www.ece.msstate.edu/courses/ece3724/main_pic24/docs/sphinx/textbook_examples.html>`_.
Contributing
============
This is a fairly basic implementation; much improvement is needed! Please use the `issue tracker <http://bitbucket.org/bjones/documentation/issues?status=new&status=open>`_ to report bugs or request features; even better, contribute to the code at the CodeChat_ homepage!
License
=======
Copyright (C) 2012-2015 Bryan A. Jones.
This file is part of CodeChat.
CodeChat is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
CodeChat is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with CodeChat. If not, see <http://www.gnu.org/licenses/>.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
CodeChat-1.0.0.zip
(63.1 kB
view details)
Built Distribution
CodeChat-1.0.0-py2-none-any.whl
(63.6 kB
view details)
File details
Details for the file CodeChat-1.0.0.zip.
File metadata
- Download URL: CodeChat-1.0.0.zip
- Upload date:
- Size: 63.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | bec3c8a226272314d0e5269f6a827e8d699a4bbb97fa82f994f416fd11ad7a14 |
|
| MD5 | 77280379909ab25a7f8da8e013d6b5ce |
|
| BLAKE2b-256 | d36ebc447d26ee7758beb7c05152f516d9d558f0902db6ae61f50779883efb70 |
File details
Details for the file CodeChat-1.0.0-py2-none-any.whl.
File metadata
- Download URL: CodeChat-1.0.0-py2-none-any.whl
- Upload date:
- Size: 63.6 kB
- Tags: Python 2
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 33073c3e803f466e8cb2d70384f14aa0f77fc67f1443448fcb45a33a812040e4 |
|
| MD5 | 50e8a859e0839d21827a71fd835c5804 |
|
| BLAKE2b-256 | 2c32865d9db1168d3f8425045a0fe0980b6a19f0e1c77be5439566ceee9d517a |
