Skip to content

Commit 79c16b7

Browse files
alandefreitasalandefreitas
committed
Rename documentation to docs
1 parent a902ab4 commit 79c16b7

File tree

1,254 files changed

+4529
-210
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,254 files changed

+4529
-210
lines changed

‎README.md

+206-207
Large diffs are not rendered by default.

‎_config.yml

-3
This file was deleted.

‎docs/.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
_site
2+
.jekyll-metadata
3+
Gemfile.lock

‎documentation/GALLERY.md ‎docs/COMPLETE_GALLERY.md

+5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
layout: default
3+
title: 404
4+
nav_exclude: true
5+
---
16
# Complete Gallery
27

38
## Line Plots

‎docs/Gemfile

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# frozen_string_literal: true
2+
3+
source "https://rubygems.org"
4+
5+
git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
6+
7+
# gem "rails"
8+
9+
gem "github-pages", group: :jekyll_plugins
10+
gem "just-the-docs"

‎documentation/README.md ‎docs/README.md

+5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
layout: default
3+
title: Documentation
4+
nav_exclude: true
5+
---
16
# **Matplot++**
27

38
Data visualization can help programmers and scientists identify trends in their data and efficiently communicate these results with their peers.

‎docs/_config.yml

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
remote_theme: pmarsceill/just-the-docs
2+
#theme: "just-the-docs"
3+
title: Matplot++
4+
description: A C++ Graphics Library for Data Visualization 📊🗾
5+
6+
search_enabled: false
7+
8+
aux_links:
9+
"Matplot++ on GitHub":
10+
- "//github.com/alandefreitas/matplotplusplus"
11+
12+
footer_content: "Copyright &copy; Alan Freitas. Distributed by an <a href=\"https://github.com/alandefreitas/matplotplusplus/tree/master/LICENSE.txt\">MIT license.</a>"

‎docs/coding-styles.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
layout: default
3+
title: Coding styles
4+
nav_order: 4
5+
has_children: true
6+
has_toc: false
7+
---
8+
# Coding styles
9+
10+
11+
12+
- [Member vs. Free-standing Functions](coding-styles/member-vs-free-standing-functions.md)
13+
- [Reactive figures](coding-styles/reactive-figures.md)
14+
- [Method Chaining](coding-styles/method-chaining.md)
15+
- [Ranges](coding-styles/ranges.md)
16+
- [Common Utilities](coding-styles/common-utilities.md)

‎docs/coding-styles/common-utilities.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
layout: default
3+
title: Common Utilities
4+
nav_order: 5
5+
has_children: false
6+
parent: Coding styles
7+
has_toc: false
8+
---
9+
# Common Utilities
10+
11+
The headers `common.h` and `colors.h` include a number of utilities we use in our examples. These include naive functions to generate and manipulate vectors and strings; handle RGBA color arrays; convert points to and from polar coordinates; read files to strings; write strings to files; calculate gradients; read, write, and manipulate images; and generate vectors with random numbers. Although some of these functions might be helpful, most functions only operate on `vector<double>` and they are not intended to be a library of utilities. The sole purpose of these algorithms is to simplify the examples.
12+
13+
14+

‎docs/coding-styles/member-vs-free-standing-functions.md

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
layout: default
3+
title: Member vs. Free-standing Functions
4+
nav_order: 1
5+
has_children: false
6+
parent: Coding styles
7+
has_toc: false
8+
---
9+
# Member vs. Free-standing Functions
10+
11+
Like in Matplotlib, we support two coding styles: Free-standing functions and an Object-oriented interface.
12+
13+
* Freestanding functions:
14+
- We call functions to create plots on the current axes
15+
- The global current `axes` object is the current `axes` object in the current figure in the global figure registry
16+
- For instance, one can use `plot(y);` to create a line plot on the current axes (or create a new `axes` object if needed).
17+
- Also, one can use `plot(ax,y);` to create a line plot on the `axes` object `ax`.
18+
- This is less verbose for small projects and quick tests.
19+
- The library looks for existing axes to create the plot.
20+
21+
* Object-oriented interface:
22+
- We explicitly create figures and call methods on them
23+
- For instance, one can use `ax->plot(y);` to plot on the `axes` object `ax`
24+
- We can create the same line plot on the current axes by `auto ax = gca(); ax->plot(y);`
25+
- This is less verbose and provides better control in large projects where we need to pass these objects around
26+
- The user manages axes handles containing plots.
27+
28+
Assuming the user is explicitly managing the axes to create plots in another function, a more complete example of these styles could be
29+
30+
```cpp
31+
// Free-standing functions
32+
auto ax = gca();
33+
plot(ax, x, y)->color("red").line_width(2);
34+
my_function(ax);
35+
```
36+
37+
and
38+
39+
```cpp
40+
// Object-oriented interface
41+
auto ax = gca();
42+
ax->plot(x, y)->color("red").line_width(2);
43+
my_function(ax);
44+
```
45+
46+
Both examples would generate the same plot. All free-standing functions are templated functions that use meta-programming to call the main function on the current `axes` object. If the first parameter is not an `axes_handle`, it will get an `axes_handle` from the figure registry with `gca` (Section [Axes Object](../examples/appearance/axes-object.md)) and forward all parameters to the function in this `axes` object. If the first parameter is an `axes_handle`, the template function will forward all parameters, but the first one, to this `axes` object. This use of templates for the free-standing functions keeps both coding styles maintainable by the developers.
47+
48+
Note that, because the example needs the `axes` object for the function `my_function`, we also need to get a reference to the `axes` object with the free-standing functions. In that case, the free-standing functions are not less verbose than the object-oriented interface.
49+
50+
To adhere to free-standing functions, we could create two versions of `my_function`: one that receives an `axes_handle`, and a second version that would get an `axes_handle` from the figure registry and call the first version. If `my_function` is going to be exposed to other users as a library, this could be a convenience to these users. However, notice that this is only moving the verbosity from the main function to `my_function`. In fact, this is how the free-standing functions in **Matplot++** work.
51+
52+
53+

‎docs/coding-styles/method-chaining.md

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
layout: default
3+
title: Method Chaining
4+
nav_order: 3
5+
has_children: false
6+
parent: Coding styles
7+
has_toc: false
8+
---
9+
# Method Chaining
10+
11+
To support a more compact syntax, the library allows method chaining on plot objects. For instance, we can create a simple line plot and modify its appearance by
12+
13+
```cpp
14+
// Using the line handle
15+
auto p = plot(x,y,"--gs");
16+
p->line_width(2);
17+
p->marker_size(10);
18+
p->marker_color("b");
19+
p->marker_face_color({.5,.5,.5});
20+
```
21+
22+
or
23+
24+
```cpp
25+
// Method chaining
26+
plot(x,y,"--gs")->line_width(2).marker_size(10).marker_color("b").marker_face_color({.5,.5,.5});
27+
```
28+
29+
The first code snippet works because `plot` returns a `line_handle` to the object in the `axes`. We can use this line handle to modify the line plot. Whenever we modify a property, the setter function calls `touch`, which will `draw` the figure again if it is in reactive mode. The second option works because setters return a reference to `*this` rather than void.
30+
31+
32+

‎docs/coding-styles/ranges.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
layout: default
3+
title: Ranges
4+
nav_order: 4
5+
has_children: false
6+
parent: Coding styles
7+
has_toc: false
8+
---
9+
# Ranges
10+
11+
12+
The plotting functions work on any range of elements convertible to `double`. For instance, we can create a line plot from a set of elements by
13+
14+
```cpp
15+
set<int> y = {6,3,8,2,5};
16+
plot(y);
17+
```
18+
19+
Any object that has the functions `begin` and `end` are considered iterable ranges. Most `axes object` subclasses use `vector<double>` or `vector<vector<double>>` to store their data. For convenience, the `common.h` header file includes the aliases `vector_1d` and `vector_2d` to these data types.
20+
21+
These conversions also work on ranges of ranges:
22+
23+
```cpp
24+
vector<set<int>> Y = { {6, 3, 8, 2, 5}, {6, 3, 5, 8, 2} };
25+
plot(Y);
26+
```
27+
28+
Unfortunately, because of how templated functions work, one exception is initializer lists. Initializer lists only work for functions that are explicitly defined for them.
29+
30+
31+

‎docs/coding-styles/reactive-figures.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
layout: default
3+
title: Reactive figures
4+
nav_order: 2
5+
has_children: false
6+
parent: Coding styles
7+
has_toc: false
8+
---
9+
# Reactive figures
10+
11+
There are also two modes for figures: reactive (or interactive) mode and quiet mode. Figures in reactive mode are updated whenever any of their child objects change. This happens through the `touch` function, that gets called on any child object when it changes its appearance. This creates an interactive mode in which figures are updated as soon as we adjust their properties. If we combine interactive figures with free-standing functions, we have a "Matlab-like style" for plots. This is a coding pattern where the figure registry works as a stream for plots.
12+
The problem with this coding style is that the user might unnecessarily create useless intermediary plots.
13+
14+
Figures in quiet mode are updated by calling the functions `draw()` or `show()` (Section [Reactive Figures](reactive-figures.md)). Unless these functions are called, nothing changes in the figure. The combination of the object-oriented coding style and quiet mode is the "OO-Matplotlib-like style" for plots. This is a coding style in which the user explicitly decides when the plot is shown or updated. This is beneficial to applications that cannot waste computational resources on intermediary figures that might not be valuable to the application.
15+
16+
We generally use free-standing functions with reactive mode and the object-oriented interface with quiet mode. By default, new figures are in reactive mode, unless it is using an non-interactive backend. One can turn this reactive mode on and off with:
17+
18+
19+
* `ion()` or `ioff()` free-standing functions
20+
* `reactive(bool)` or `quiet(bool)` function on the `figure` object
21+
* `figure(true)` or `figure(false)` when explicitly creating a new figure
22+
23+
A more complete example of the reactive mode would be:
24+
25+
```cpp
26+
// Reactive mode
27+
auto f = gcf(false);
28+
auto ax = f->gca();
29+
auto p = ax->plot(ax, x, y); // draws once
30+
p->color("red").line_width(2); // draws twice more
31+
wait(); // pause console
32+
```
33+
34+
For convenience, the examples in Section [Examples](../examples.md) use the reactive mode. The `wait` function pauses the console until the user interacts with the plot window. If the backend is based on process pipes, because these are unidirectional, closing the window is not enough to resume. The user needs to use the console to unblock execution. A similar example is quiet mode would be
35+
36+
```cpp
37+
// Quiet mode
38+
auto f = gcf(true);
39+
auto ax = f->gca();
40+
auto p = ax->plot(x,y); // does not draw
41+
p->color("red").line_width(2); // does not draw
42+
f->show(); // draw only once and pause console
43+
```
44+
45+
In this example, the figure is only updated once. The user could replace the `show` function with the `draw` function, but the window would close as soon as execution completes. It is important to use `wait()` and `show()` with caution. These functions are meant for some particular executables so that an interactive plot does not close before the user can see it. It is probably unreasonable to call these functions inside a library because the user would have to manually interfere with the execution to continue.
46+
47+
48+

‎docs/contributing.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
layout: default
3+
title: Contributing
4+
nav_order: 7
5+
has_children: true
6+
has_toc: false
7+
---
8+
# Contributing
9+
10+
There are many ways in which you can contribute to this library:
11+
12+
* Testing the library in new environments <sup>see [1](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22cross-platform+issue+-+windows%22), [2](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22cross-platform+issue+-+linux%22), [3](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22cross-platform+issue+-+macos%22) </sup>
13+
* Contributing with interesting examples <sup>see [1](../source/examples)</sup>
14+
* Designing new backends <sup>see [1](....inREADME.md#backendsnds/ogl_main.cppckend_interface.h), [2](test/backends/ogl_main.cpp), [3](#backends), [4](docs/README.md#backends)</sup>
15+
* Finding problems in this documentation <sup>see [1](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22enhancement+-+documentation%22) </sup>
16+
* Writing algorithms for new plot categories <sup>see [1](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22enhancement+-+plot+categories%22) </sup>
17+
* Finding bugs in general <sup>see [1](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22bug+-+compilation+error%22), [2](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22bug+-+compilation+warning%22), [3](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22bug+-+runtime+error%22), [4](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22bug+-+runtime+warning%22) </sup>
18+
* Whatever idea seems interesting to you
19+
20+
If contributing with code, please leave the OpenGL backend and pedantic mode ON (`-DBUILD_EXPERIMENTAL_OPENGL_BACKEND=ON -DBUILD_WITH_PEDANTIC_WARNINGS=ON`).
21+
22+
23+
Example: CLion
24+
25+
![CLion Settings with Pedantic Mode](img/pedantic_clion.png)
26+
27+
28+
29+
30+
31+
- [Contributors](contributing/contributors.md)

‎docs/contributing/contributors.md

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
layout: default
3+
title: Contributors
4+
nav_order: 1
5+
has_children: false
6+
parent: Contributing
7+
has_toc: false
8+
---
9+
# Contributors
10+
11+
<!-- readme: collaborators,contributors -start -->
12+
<table>
13+
<tr>
14+
<td align="center">
15+
<a href="https://github.com/alandefreitas">
16+
<img src="https://avatars0.githubusercontent.com/u/5369819?v=4" width="100;" alt="alandefreitas"/>
17+
<br />
18+
<sub><b>Alan De Freitas</b></sub>
19+
</a>
20+
</td>
21+
<td align="center">
22+
<a href="https://github.com/mrexodia">
23+
<img src="https://avatars2.githubusercontent.com/u/2458265?v=4" width="100;" alt="mrexodia"/>
24+
<br />
25+
<sub><b>Duncan Ogilvie</b></sub>
26+
</a>
27+
</td>
28+
<td align="center">
29+
<a href="https://github.com/lacc97">
30+
<img src="https://avatars1.githubusercontent.com/u/23489037?v=4" width="100;" alt="lacc97"/>
31+
<br />
32+
<sub><b>Luis Cáceres</b></sub>
33+
</a>
34+
</td>
35+
<td align="center">
36+
<a href="https://github.com/xnorpx">
37+
<img src="https://avatars2.githubusercontent.com/u/302709?v=4" width="100;" alt="xnorpx"/>
38+
<br />
39+
<sub><b>Marcus Asteborg</b></sub>
40+
</a>
41+
</td>
42+
<td align="center">
43+
<a href="https://github.com/sammi">
44+
<img src="https://avatars0.githubusercontent.com/u/189128?v=4" width="100;" alt="sammi"/>
45+
<br />
46+
<sub><b>Sammi</b></sub>
47+
</a>
48+
</td>
49+
<td align="center">
50+
<a href="https://github.com/dimztimz">
51+
<img src="https://avatars0.githubusercontent.com/u/6236568?v=4" width="100;" alt="dimztimz"/>
52+
<br />
53+
<sub><b>Dimitrij Mijoski</b></sub>
54+
</a>
55+
</td></tr>
56+
</table>
57+
<!-- readme: collaborators,contributors -end -->
58+
59+
60+

0 commit comments

Comments
 (0)