Switch to reStructuredText for documentation.

This commit is contained in:
Thomas Wilburn 2014-09-05 08:41:16 -07:00
parent 18c3d78834
commit 6c3aa57276
11 changed files with 305 additions and 233 deletions

View file

@ -1,62 +0,0 @@
# Module descriptions - core
This document serves as basic documentation for Caret's AMD modules. It's not
exhaustive, but it will serve as a starting place for anyone wanting to dive
in a little deeper.
Caret's execution starts in main.js, which mostly serves as bootstrap for the
other modules. It also registers command listeners for the UI themes, various
window events, and app-level commands like `app:check-for-updates`. After
that, we really get down to business.
In addition to the module folders, which contain their own readme files, there
are also folders for the current Ace build (ace) and any external libraries
used by Caret, such as the ES6 Promises shim (lib).
## aceBindings.js
Takes care of any messiness between Caret and Ace APIs. Registers the
`ace:command` listener, as well as a bunch of Sublime emulation commands.
Exposes no external methods or data.
## api.js
Registers for chrome.runtime.onMessageExternal events, patching them into the
command module, and dispatches messages from `api:execute` commands. Exposes
no external methods or data.
## command.js
Serves as a messaging buffer between modules, and from declarative DOM
attributes to modules. Exposes three properties: `fire()` for sending
commands, `on()` for subscribing to them, and an array called `list` that can
be used to add palette-only items at runtime.
## editor.js
Sets up the Ace editor and registers for events in the `editor:*` namespace.
Returns the Ace object.
## fileManager.js
Handles opening files from launch data, retained handles, and user commands.
Exposes no external methods or data.
## sessions.js
Manages Caret's tabs, including all UI interaction with the tab bar and the
process of adding or removing tabs. Exposes a number of methods and
manipulating the tab structure. Most of the actual session code is loaded from the `/sessions` folder, to make the file more manageable.
## settings.js
Runs as a RequireJS plugin, so that dependent modules can rely on having
settings available on startup, but actually just returns the same singleton
as `storage/settingsProvider`.
## tab.js
Exposes a Tab constructor to dependents, which is an augmented Ace
EditorSession. Tabs do additional setup work to support Caret, as well as
adding methods for saving files and dropping retained file handles.

71
js/readme.rst Normal file
View file

@ -0,0 +1,71 @@
Module descriptions - core
==========================
This document serves as basic documentation for Caret's AMD modules.
It's not exhaustive, but it will serve as a starting place for anyone
wanting to dive in a little deeper.
Caret's execution starts in main.js, which mostly serves as bootstrap
for the other modules. It also registers command listeners for the UI
themes, various window events, and app-level commands like
``app:check-for-updates``. After that, we really get down to business.
In addition to the module folders, which contain their own readme files,
there are also folders for the current Ace build (ace) and any external
libraries used by Caret, such as the ES6 Promises shim (lib).
aceBindings.js
--------------
Takes care of any messiness between Caret and Ace APIs. Registers the
``ace:command`` listener, as well as a bunch of Sublime emulation
commands. Exposes no external methods or data.
api.js
------
Registers for chrome.runtime.onMessageExternal events, patching them
into the command module, and dispatches messages from ``api:execute``
commands. Exposes no external methods or data.
command.js
----------
Serves as a messaging buffer between modules, and from declarative DOM
attributes to modules. Exposes three properties: ``fire()`` for sending
commands, ``on()`` for subscribing to them, and an array called ``list``
that can be used to add palette-only items at runtime.
editor.js
---------
Sets up the Ace editor and registers for events in the ``editor:*``
namespace. Returns the Ace object.
fileManager.js
--------------
Handles opening files from launch data, retained handles, and user
commands. Exposes no external methods or data.
sessions.js
-----------
Manages Caret's tabs, including all UI interaction with the tab bar and
the process of adding or removing tabs. Exposes a number of methods and
manipulating the tab structure. Most of the actual session code is
loaded from the ``/sessions`` folder, to make the file more manageable.
settings.js
-----------
Runs as a RequireJS plugin, so that dependent modules can rely on having
settings available on startup, but actually just returns the same
singleton as ``storage/settingsProvider``.
tab.js
------
Exposes a Tab constructor to dependents, which is an augmented Ace
EditorSession. Tabs do additional setup work to support Caret, as well
as adding methods for saving files and dropping retained file handles.

View file

@ -1,21 +1,27 @@
# Module description - sessions/*
Module description - sessions/\*
================================
The sessions folder contains functionality that was broken out to keep
`sessions.js` from getting huge.
``sessions.js`` from getting huge.
## addRemove.js
addRemove.js
------------
Provides methods for adding, removing, and re-ordering sessions and their tabs.
Provides methods for adding, removing, and re-ordering sessions and
their tabs.
## binding.js
binding.js
----------
Event bindings, such as drag/drop and middle click
## state.js
state.js
--------
Actual tab state as a singleton, imported by other modules to do re-ordering or
other tab manipulation.
Actual tab state as a singleton, imported by other modules to do
re-ordering or other tab manipulation.
## switching.js
switching.js
------------
Provides the utility methods for between tabs, directly or in order.
Provides the utility methods for between tabs, directly or in order.

View file

@ -1,45 +0,0 @@
# Module descriptions - storage/*
## file.js
Wraps the chrome.fileSystem APIs in a friendly File constructor. File objects
have the following methods or properties, most of which should be self
explanatory. Most methods return promises, but also accept node-style callbacks.
- `open`
- `read`
- `write`
- `stat`
- `retain`
- `restore`
- `getPath`
- `entry` - contains the actual entry object.
All storage in Caret, regardless of its actual backing structure, goes through
objects adhering to the File interface, which makes it much easier to open
many types of data through the same tab/editor UI. It also makes persistence
much more consistent and less verbose throughout Caret.
## settingsProvider.js
The actual singleton returned when modules load configs via the `settings`
plugin. Provides the following API:
- `get` Retrieves the current settings object by name, with all layers `(project, local, and default) merged over top each other.
- `getAsString` Retrieves the local settings as a string, mostly used when opening settings for editing.
- `getAsFile`
- `load` Requests a fresh copy of the local settings from sync storage, usually called after either writing to settings or when the dependent module does not have a settings cache.
- `setProject` Sets the top-most JSON object to be merged when calling `Settings.get()`, used for the project-specific settings overrides.
- `clearProject` Removes the top-most JSON object, so that only local and default settings are merged.
- `pull` Calls load/get for you on the list of arguments, and returns a promise that's fullfilled with a hash of the requested settings.
## syncfile.js
A constructor matching the File interface, but backed by chrome.storage.sync.
Used to open settings "files."
## syncFS.js
An abstraction over top of chrome.storage.sync, capable of storing data larger
than the sync storage limit by splitting it into multiple entries behind the
scenes. Returns promises for all methods.

60
js/storage/readme.rst Normal file
View file

@ -0,0 +1,60 @@
Module descriptions - storage/\*
================================
file.js
-------
Wraps the chrome.fileSystem APIs in a friendly File constructor. File
objects have the following methods or properties, most of which should
be self explanatory. Most methods return promises, but also accept
node-style callbacks.
- ``open``
- ``read``
- ``write``
- ``stat``
- ``retain``
- ``restore``
- ``getPath``
- ``entry`` - contains the actual entry object.
All storage in Caret, regardless of its actual backing structure, goes
through objects adhering to the File interface, which makes it much
easier to open many types of data through the same tab/editor UI. It
also makes persistence much more consistent and less verbose throughout
Caret.
settingsProvider.js
-------------------
The actual singleton returned when modules load configs via the
``settings`` plugin. Provides the following API:
- ``get`` Retrieves the current settings object by name, with all
layers \`(project, local, and default) merged over top each other.
- ``getAsString`` Retrieves the local settings as a string, mostly used
when opening settings for editing.
- ``getAsFile``
- ``load`` Requests a fresh copy of the local settings from sync
storage, usually called after either writing to settings or when the
dependent module does not have a settings cache.
- ``setProject`` Sets the top-most JSON object to be merged when
calling ``Settings.get()``, used for the project-specific settings
overrides.
- ``clearProject`` Removes the top-most JSON object, so that only local
and default settings are merged.
- ``pull`` Calls load/get for you on the list of arguments, and returns
a promise that's fullfilled with a hash of the requested settings.
syncfile.js
-----------
A constructor matching the File interface, but backed by
chrome.storage.sync. Used to open settings "files."
syncFS.js
---------
An abstraction over top of chrome.storage.sync, capable of storing data
larger than the sync storage limit by splitting it into multiple entries
behind the scenes. Returns promises for all methods.

View file

@ -1,47 +0,0 @@
# Module description - ui/*
## cli.js
Creates the UI and bindings for a "command line" that can run Caret commands
directly. Useful when testing a new command, since you don't need to change
keys.json or menu.json in order to run it.
## contextMenus.js
Simplifies the process of adding Chrome context menus to page links, including
adding a basic REST-style router for getting parameters out of the link URL.
Exposes a `register` method for setting up the actual menu and its callback,
and a `makeURL` method to help with making route URLs that correctly start
with the app's extension ID.
## dialog.js
Exposes a function that will pop up a dialog box, since Chrome apps are not
allowed to use `alert()`, `confirm()`, or `prompt()`. Reasonably customizable.
## keys.js
Reads the local keyboard settings and registers on the document body to
convert them into commands. Also handles unbinding any Ace commands that would
otherwise collide. Exposes no external methods or data.
## menus.js
Generates the menu bar from the local menu settings file. Exposes no external
methods or data at this time.
## palette.js
Sets up the command palette and returns it as a singleton for any other
modules that might want to trigger it or alter its data, although it is
recommended that other modules simply send `palette:*` commands instead.
## projectManager.js
Tracks any current project settings, files, and navigable directories. Exposes
the manager object to dependent modules, primarily so that the palette can get
the list of files for Go To File.
## statusbar.js
Sets the status text, and returns an interface with `setMessage()`, `clearMessage()`, and `toast()` methods. It's recommended to use the `status:*` commands instead of requiring this module directly.

60
js/ui/readme.rst Normal file
View file

@ -0,0 +1,60 @@
Module description - ui/\*
==========================
cli.js
------
Creates the UI and bindings for a "command line" that can run Caret
commands directly. Useful when testing a new command, since you don't
need to change keys.json or menu.json in order to run it.
contextMenus.js
---------------
Simplifies the process of adding Chrome context menus to page links,
including adding a basic REST-style router for getting parameters out of
the link URL. Exposes a ``register`` method for setting up the actual
menu and its callback, and a ``makeURL`` method to help with making
route URLs that correctly start with the app's extension ID.
dialog.js
---------
Exposes a function that will pop up a dialog box, since Chrome apps are
not allowed to use ``alert()``, ``confirm()``, or ``prompt()``.
Reasonably customizable.
keys.js
-------
Reads the local keyboard settings and registers on the document body to
convert them into commands. Also handles unbinding any Ace commands that
would otherwise collide. Exposes no external methods or data.
menus.js
--------
Generates the menu bar from the local menu settings file. Exposes no
external methods or data at this time.
palette.js
----------
Sets up the command palette and returns it as a singleton for any other
modules that might want to trigger it or alter its data, although it is
recommended that other modules simply send ``palette:*`` commands
instead.
projectManager.js
-----------------
Tracks any current project settings, files, and navigable directories.
Exposes the manager object to dependent modules, primarily so that the
palette can get the list of files for Go To File.
statusbar.js
------------
Sets the status text, and returns an interface with ``setMessage()``,
``clearMessage()``, and ``toast()`` methods. It's recommended to use the
``status:*`` commands instead of requiring this module directly.

View file

@ -1,46 +0,0 @@
# Module descriptions - util
## aceLoad.js
Shims Ace's loadScript() async loader so that AMD modules can simply declare Ace dependencies the same way they declare AMD dependencies.
## dom2.js
Instead of using an MVC framework like Backbone or a view binding library like
Angular, Caret modifies the DOM prototypes to have a more jQuery-like UI with
this module. Since Chrome apps cannot share a page with external scripts, and
since we know that the Chrome DOM prototypes are stable, this is a safe and
easy way to get sensible DOM manipulation. Exposes no methods or data, but
does modify the Document, DocumentFragment, Element, and Window prototypes.
## inflate.js
Chrome OS disallows using `eval()` or `new Function()`, which means many
template libraries simply won't work without pre-compiling the templates.
Instead of going that route, recognizing that template speed is almost never a
bottleneck for Caret, inflate.js provides Mustache-compatible templating that
can load from the filesystem or the DOM (loaded automatically by ID). Exposes
the following methods:
- `load`- Pulls a template from the given filesystem path. Returns a promise that resolves when the template is ready.
- `loadHTML` - Directly insert HTML into the template cache for use.
- `get` - Fills a template with data and returns a DOM element.
- `getHTML` - Fills a template with data and returns the string representation
- `getAsync` - Used to simultaneously load and fill a template. Returns a promise that resolves with the filled template as a DOM element.
## manos.js
A lightweight library for handling async code, this serves as the "hands of
fate" for your callbacks. Provides `serial()` and `map()` for async array
manipulation, and `pton()` and `deferred` for working with native ES6
Promises.
## template.js
A plugin that loads a template from disk, then returns the `inflate` templating
object. Useful for modules that need a template as part of their dependencies.
## text.js
A RequireJS plugin that loads files from Caret's app directory using XHR. Used
to get the default settings JSON through a standard interface.

60
js/util/readme.rst Normal file
View file

@ -0,0 +1,60 @@
Module descriptions - util
==========================
aceLoad.js
----------
Shims Ace's loadScript() async loader so that AMD modules can simply
declare Ace dependencies the same way they declare AMD dependencies.
dom2.js
-------
Instead of using an MVC framework like Backbone or a view binding
library like Angular, Caret modifies the DOM prototypes to have a more
jQuery-like UI with this module. Since Chrome apps cannot share a page
with external scripts, and since we know that the Chrome DOM prototypes
are stable, this is a safe and easy way to get sensible DOM
manipulation. Exposes no methods or data, but does modify the Document,
DocumentFragment, Element, and Window prototypes.
inflate.js
----------
Chrome OS disallows using ``eval()`` or ``new Function()``, which means
many template libraries simply won't work without pre-compiling the
templates. Instead of going that route, recognizing that template speed
is almost never a bottleneck for Caret, inflate.js provides
Mustache-compatible templating that can load from the filesystem or the
DOM (loaded automatically by ID). Exposes the following methods:
- ``load``- Pulls a template from the given filesystem path. Returns a
promise that resolves when the template is ready.
- ``loadHTML`` - Directly insert HTML into the template cache for use.
- ``get`` - Fills a template with data and returns a DOM element.
- ``getHTML`` - Fills a template with data and returns the string
representation
- ``getAsync`` - Used to simultaneously load and fill a template.
Returns a promise that resolves with the filled template as a DOM
element.
manos.js
--------
A lightweight library for handling async code, this serves as the "hands
of fate" for your callbacks. Provides ``serial()`` and ``map()`` for
async array manipulation, and ``pton()`` and ``deferred`` for working
with native ES6 Promises.
template.js
-----------
A plugin that loads a template from disk, then returns the ``inflate``
templating object. Useful for modules that need a template as part of
their dependencies.
text.js
-------
A RequireJS plugin that loads files from Caret's app directory using
XHR. Used to get the default settings JSON through a standard interface.

View file

@ -1,23 +0,0 @@
Caret
=====
Caret is a serious, graphical programmer's editor running as a Chrome Packaged App. Inspired by Sublime and built on top of the Ace editing component, it offers powerful features like:
* multiple cursors
* tabbed editing and retained files
* syntax highlighting and themes
* command palette/smart go to
* hackable, synchronized configuration files
* project files and folder view
More information, links to Caret in the Chrome Web Store, and an external package file are available at http://thomaswilburn.net/caret. Documentation can be found in the [wiki](https://github.com/thomaswilburn/Caret/wiki).
You can also easily load Caret from source, either to hack around on or to have the absolute bleeding edge. You'll need to have Node and NPM installed first, then follow these steps:
0. Clone this repo to your local machine
0. Run `npm install` to get the development dependencies (Grunt, LESS, and some other packages)
0. Start `grunt`, which will generate the CSS files from the LESS source
0. Visit `chrome://extensions` and enable Developer Mode.
0. Still on the extensions page, click the button marked "Load unpacked extension..." and select the directory containing Caret's manifest.json.
If you use Caret and would like to show your appreciation, please consider donating to the [EFF's Fund to End Software Patents](https://my.fsf.org/donate/directed-donations/esp). You can also give a gift through [Gittip](https://www.gittip.com/thomaswilburn/).

38
readme.rst Normal file
View file

@ -0,0 +1,38 @@
Caret
=====
Caret is a serious, graphical programmer's editor running as a Chrome
Packaged App. Inspired by Sublime and built on top of the Ace editing
component, it offers powerful features like:
- multiple cursors
- tabbed editing and retained files
- syntax highlighting and themes
- command palette/smart go to
- hackable, synchronized configuration files
- project files and folder view
More information, links to Caret in the Chrome Web Store, and an
external package file are available at http://thomaswilburn.net/caret.
Documentation can be found in the
`wiki <https://github.com/thomaswilburn/Caret/wiki>`__.
You can also easily load Caret from source, either to hack around on or
to have the absolute bleeding edge. You'll need to have Node and NPM
installed first, then follow these steps:
0. Clone this repo to your local machine
1. Run ``npm install`` to get the development dependencies (Grunt, LESS,
and some other packages)
2. Start ``grunt``, which will generate the CSS files from the LESS
source
3. Visit ``chrome://extensions`` and enable Developer Mode.
4. Still on the extensions page, click the button marked "Load unpacked
extension..." and select the directory containing Caret's
manifest.json.
If you use Caret and would like to show your appreciation, please
consider donating to the `EFF's Fund to End Software
Patents <https://my.fsf.org/donate/directed-donations/esp>`__. You can
also give a gift through
`Gittip <https://www.gittip.com/thomaswilburn/>`__.