Merge pull request #2 from ba-st/docs

Add documentation

.travis.yml

@@ -1,15 +1,26 @@
 language: smalltalk
 sudo: false
-
 os:
   - linux
-
 smalltalk:
   - Pharo64-7.0
   - Pharo-7.0
   - Pharo-6.1
-
 matrix:
   allow_failures:
   - smalltalk: Pharo64-7.0
   - smalltalk: Pharo-7.0
+  fast_finish: true
+before_deploy:
+  - cp "${SMALLTALK_CI_IMAGE}" "Mole.image"
+  - cp "${SMALLTALK_CI_CHANGES}" "Mole.changes"
+  - zip -q "${TRAVIS_BRANCH}-${TRAVIS_SMALLTALK_VERSION}.zip" "Mole.image" "Mole.changes"
+deploy:
+  provider: releases
+  api_key:
+    secure: mRoJUKUQh6g2L0HhP51Leg6EKwVdXxclEjsC9ZSMooEVmQseftE/QNpW4D2bViI1ZE9pMRuUFoFvxRn0ZfruIFGT8fCo4Df+QY4HUDueWsj2m4zfuAzuibGvLCH+44W5IBdcv37dRDsS7lNOZg8lOkzJEMqrecLFH91jdLovomITNaPl06EJ4kP49V7xZtHkMeHHTjW7m7JhcJVIHHoTlQxNbpoRLUGrCjFKZToyXeMmkE5KZLM3rJVgsN8ja/CBLtarVSz4hRaQmRSxktoaKdK01eRWCk2WDvjMmizdhb9W9NQbw9pXpVXW1l2cB3xdZraatOSHXan2SpnhGfHymYDQQMLH03Gof61jGEB08SqGZRHnpcGU781raGbheXzPxlg9DJSsWz1893NFi4ztAwaSsvhl3DibeGjG9pCn4vf4op9DEu+9tQIdJBqtE7rjPbBArnncE6FA7ZnoZ0ZbnDb2X+0kE6S5AjuZPEFNS1Xiqo/zd1uJNCk10L9d6QO2oDDf6iyYKchJIksgN8i5qkzEqLYiXeTDY25LfZytvuIOUu5nYtSHD/HHx4W7Xo8AfxiLM7pQUCnuqxj9XmROBwRGXHmLfm5cGkveuzOjvmhs3Pt4ExQLhXyv45fxwOxAUsCPLrJoVDwZ/mmDyAyXQwzkmUnMTH5bJ/665/CGhAY=
+  file: "${TRAVIS_BRANCH}-${TRAVIS_SMALLTALK_VERSION}.zip"
+  skip_cleanup: true
+  on:
+    repo: ba-st/Mole
+    tags: true

README.md

@@ -1,9 +1,30 @@
 ![Logo](resources/128.png) Mole
 ===============================
+![Latest Release](https://img.shields.io/github/release/ba-st/Mole.svg) [![Build Status](https://travis-ci.org/ba-st/Mole.svg?branch=master)](https://travis-ci.org/ba-st/Mole)
+[![Coverage Status](https://coveralls.io/repos/github/ba-st/Mole/badge.svg?branch=master)](https://coveralls.io/github/ba-st/Mole?branch=master)
 
-Mole is a minimal directed graph model to perform topological sort on it.
+*Mole provides a model for graphs, both directed and undirected.*
 
-Name origin: this is a Topological model, which can be shortened to [**Topo**](https://es.wikipedia.org/wiki/Talpidae), the Spanish word for [Mole](https://en.wikipedia.org/wiki/Mole_(animal)).
+> *Name origin*: This project started as a topological model, which can be shortened to [**Topo**](https://es.wikipedia.org/wiki/Talpidae), the Spanish word for [Mole](https://en.wikipedia.org/wiki/Mole_(animal)).
 
-[![Build Status](https://travis-ci.org/ba-st/Mole.svg?branch=master)](https://travis-ci.org/ba-st/Mole)
-[![Coverage Status](https://coveralls.io/repos/github/ba-st/Mole/badge.svg?branch=master)](https://coveralls.io/github/ba-st/Mole?branch=master)
+## License
+The project source code is [MIT](LICENSE) licensed. Any contribution submitted to the code repository is considered to be under the same license.
+
+The documentation is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-sa/4.0/).
+
+## Get started!
+
+- Download a [Pharo Image and VM](http://get.pharo.org)
+- Download a ready to use image of the latest stable version in the [releases page](https://github.com/ba-st/Mole/releases).
+- Check the [documentation](docs/Mole.md)
+
+or
+- Open a Playground and evaluate:
+
+```smalltalk
+Metacello new
+  baseline: 'Mole';
+  repository: 'github://ba-st/Mole:master/source';
+  load
+```
+to get the latest changes.

docs/Mole.md

@@ -0,0 +1,75 @@
+Graphs
+======
+Mole provides a model for graphs, both directed and undirected. Graphs in Mole are immutable. A graph consists on a set of vertices and edges connecting them. Any object can be used as a vertex.
+
+Each graph can understand the following messages:
+
+### Accessing
+
+- `neighborsOf: aVertex` Returns the vertices that are connected to `aVertex`
+- `order` The number of vertices
+- `size` The number of edges
+
+### Converting
+- `withoutVertex: aVertex` Returns a new graph excluding the vertex and all it's incident edges
+- `withoutVertices: aVertexCollection` Returns a new graph excluding the vertices and all it's incident edges
+
+### Testing
+- `includesVertex: aVertex` Returns true if `aVertex` is included in the vertices
+- `is: aVertex adjacentTo: anotherVertex` Returns true if exists and edge incident to `aVertex` and `anotherVertex`
+
+## Undirected Graph
+
+Undirected graphs, graphs in which the two endpoints of each edge are not distinguished from each other, are modeled in `UndirectedGraph`.
+
+The easier way to create an undirected graph it's to use the builder: `UndirectedGraphBuilder`.
+For example:
+```smalltalk
+UndirectedGraphBuilder new
+  relate: 1 to: 2;
+  selfRelate: 1;
+  relate: 4 to: 3;
+  addVertex: 8;
+  build
+```
+will create an undirected graph with 5 vertices {1, 2, 3, 4, 8} and the following edges: { (1,2), (1,1), (4,3)}. The builder will take care of creating the right type of edge and adding the vertices included in edges automatically.
+
+In addition to the messages common to all graphs, undirected graphs also understand:
+
+- `degreeOf: aVertex`  The degree (or valency) of a vertex is the number of edges incident to the vertex.	A special case is a self loop, which adds two to the degree.
+- `edgesIncidentTo: aVertex`
+
+## Directed Graph
+
+Directed graphs, graphs where all the edges are directed from one vertex to another, are modeled in `DirectedGraph`. A directed graph is sometimes called a digraph or a directed network.
+
+The easier way to create an directed graph it's to use the builder: `DirectedGraphBuilder`.
+For example:
+```smalltalk
+DirectedGraphBuilder new
+  connect: 1 to: 2;
+  connect: 4 to: 3;
+  addVertex: 5;
+  build
+```
+will create an directed graph with 5 vertices {1, 2, 3, 4, 5} and the following edges: { 1 -> 2, 4 -> 3}.
+
+In addition to the messages common to all graphs, directed graphs also understand:
+
+### Accessing
+- `edgesIncomingTo: aVertex` Returns the edges converging to a vertex.
+- `edgesOutgoingFrom: aVertex` Returns the edges starting from a vertex.
+- `incomingDegreeOf: aVertex` Returns the number of edges converging to a vertex.
+- `outgoingDegreeOf: aVertex` Returns the number of edges starting from a vertex.
+- `topologicalSort` If the graph is acyclic returns a topological sort of its vertices. In case the graph is cyclic raises an exception.
+- `verticesReachableFrom: aSourceVertex` Returns the vertices that can be reached starting from the source vertex.
+
+### Testing
+- `isAcyclic` Returns true if the graph is acyclic
+- `isCyclic` Returns true if the graph is cyclic
+
+## Future Work
+- Traversal algorithms
+- Weighted and labeled vertices/edges
+- Walks and paths
+- Union, difference and intersection