Skip to main content

The CodeChat system for software documentation

Project description

CodeChat 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 paradigm changes the way developers think by intermingling ideas with their implementation as code, dramatically improving a programmer’s abilities.

Installation

See the installation intructions.

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 introducted literate programming using his WEB tool in his seminal paper. 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 developed over the years attempt to address these problems, only one LP-inspired variant has gained widespread acceptance: documentation generators, such as Doxygen and JavaDoc, 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 CodeChat tutorial 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.

Examples

Some examples of literate programming using CodeChat:

Contributing

This is a fairly basic implementation; much improvement is needed! Please use the issue tracker to report bugs or request features; even better, contribute to the code!

License

Copyright (C) 2012-2017 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/.

Project details


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.5.8.tar.gz (54.5 kB view details)

Uploaded Source

Built Distribution

CodeChat-1.5.8-py3-none-any.whl (61.2 kB view details)

Uploaded Python 3

File details

Details for the file CodeChat-1.5.8.tar.gz.

File metadata

  • Download URL: CodeChat-1.5.8.tar.gz
  • Upload date:
  • Size: 54.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for CodeChat-1.5.8.tar.gz
Algorithm Hash digest
SHA256 ccef72bc319af86fe7ac040affaf48f8e47e821e6b6838ba367bbf09a936ecb5
MD5 78f8b5d5bc1ff4d9819f6862443e8d12
BLAKE2b-256 47ce34510b763228a6b840205e38b6135bf9aaa271d3358ad43cd517eea2f6ea

See more details on using hashes here.

File details

Details for the file CodeChat-1.5.8-py3-none-any.whl.

File metadata

File hashes

Hashes for CodeChat-1.5.8-py3-none-any.whl
Algorithm Hash digest
SHA256 1c703c1877b9b076a8631438eff1b8bd2d1be441370c89f92cb3f04bbce9f21a
MD5 f5c9ce7f041516e7d7d5e24f04f3d654
BLAKE2b-256 717f28d1919c0e79d55ec2136f54a505262e0c68937f2d020b3cec76f41b00c2

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page