Merge pull request #14 from yacir/docs

Add the documentation

.gitignore

@@ -62,8 +62,8 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
+# Documentation
+docs/site/
 
 # PyBuilder
 target/

CHANGELOG

@@ -1,5 +1,5 @@
 ## 1.0.3 (2018-05-27)
-  * Avoid adding the `<div class="md-fenced-code-tabs"></div> structure for single code blocks if the `single_block_as_tab` option is `True`.
+  * Avoid adding the `<div class="md-fenced-code-tabs"></div>` structure for single code blocks if the `single_block_as_tab` option is `True`.
 
 ## 1.0.2 (2018-05-27)
   * **FIX**: Fixed the Bootsrap templates

README.md

@@ -1,87 +1,26 @@
-[![PyPI][pypi-image]][pypi-link]
-
-  [pypi-image]: https://img.shields.io/pypi/v/markdown-fenced-code-tabs.svg
-  [pypi-link]: https://pypi.python.org/pypi/markdown-fenced-code-tabs
+<p align="center">
+    <a href="https://pypi.python.org/pypi/markdown-fenced-code-tabs">
+        <img src="https://img.shields.io/pypi/v/markdown-fenced-code-tabs.svg"/>
+    </a>
+    <img src="https://img.shields.io/pypi/pyversions/markdown-fenced-code-tabs.svg"/>
+    <img src="https://img.shields.io/pypi/l/markdown-fenced-code-tabs.svg"/>
+</p>
 
 # Markdown Code Tabs Extension
 
-Generates Bootstrap HTML Tabs for Consecutive Markdown Fenced Code Blocks
-
-```md
-    ```http
-    GET / HTTP/1.1
-    User-Agent: MyClient/1.0.0
-    Accept: application/vnd.travis-ci.2+json
-    Host: api.travis-ci.org
-
-    HTTP/1.1 200 OK
-    Content-Type: application/json
-
-    {"hello":"world"}
-    ```
-
-    ```shell
-    $ travis raw /
-    {"hello":"world"}
-    ```
-
-    ```ruby
-    require 'travis'
-
-    # You usually don't want to fire API requests manually
-    client = Travis::Client.new
-    client.get_raw('/') # => {"hello"=>"world"}
-
-    client.get('/repos/sinatra/sinatra')
-    # => {"repo"=>#<Travis::Client::Repository: sinatra/sinatra>}
-    ```
-```
-
-Becomes:
-
-![Generated result](docs/images/img1.png)
+**Code Tabs** is an extension that generates a HTML structure for consecutive fenced code blocks content.
 
-To customize the tab label, add the `fct_label` option to your code block.
+## Quick start
 
-```md
-    ```swift fct_label="Swift 2"
-    array.enumerate()
-    ```
+Installation is easy with pip:
 
-    ```swift fct_label="Swift 3"
-    array.enumerated()
-    ```
-```
-
-![Generated result](docs/images/img2.png)
-
-## Installation
-
-Install the latest version with `pip`:
-```sh
+``` sh
 pip install markdown-fenced-code-tabs
-```
-
-## MkDocs Usage
-
-```yml
-markdown_extensions:
-  - markdown_fenced_code_tabs:
-      single_block_as_tab: True
-```
-
-## Options
-
-### `single_block_as_tab`
-If `True`, the extension will render a single code block as a tab. Default is `False`.
-
-`single_block_as_tab: True` generates:
-
-![True single_block_as_tab](docs/images/img3.png)
+``` 
 
-`single_block_as_tab: False` generates:
+For detailed installation instructions and a demo, visit
+[the documentation](https://yacir.github.io/markdown-fenced-code-tabs/).
 
-![False single_block_as_tab](docs/images/img4.png)
 
 ## Author 
 [Yassir Barchi](http://yassir.fr)

docs/mkdocs.yml

@@ -0,0 +1,51 @@
+site_name: MD Code Tabs Extension
+site_url: https://yacir.github.io/markdown-fenced-code-tabs
+repo_url: https://github.com/yacir/markdown-fenced-code-tabs
+edit_uri: tree/master/docs/src/
+site_description: Markdown extension who generates HTML tabs for consecutive fenced code blocks in markdown syntax
+copyright: |
+  Copyright &copy; 2017 - present <a href="https://github.com/yacir">Yassir Barchi</a>
+
+docs_dir: src
+theme:
+  name: material
+  language: en
+  palette:
+    primary: light-blue
+    accent: light-blue
+  logo:
+    icon: description
+  font:
+    text: 'Ubuntu'
+    code: 'Ubuntu Mono'
+  include_search_page: false
+  search_index_only: true
+
+pages:
+  - Getting Started: index.md
+  - Templates: templates.md
+  - Release Notes: release-notes.md
+  - Contributing & Support: contributing.md
+  - Licence: licence.md
+
+markdown_extensions:
+  - markdown.extensions.admonition
+  - markdown.extensions.codehilite:
+      guess_lang: false
+  - markdown.extensions.toc:
+      permalink: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:pymdownx.emoji.to_svg
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink
+  - pymdownx.smartsymbols
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.details
+  - markdown_fenced_code_tabs
+
+extra_css:
+  - 'assets/css/code-tabs.css'

docs/src/assets/css/code-tabs.css

@@ -0,0 +1,52 @@
+.md-fenced-code-tabs * {
+    box-sizing: border-box;
+}
+
+.md-fenced-code-tabs {
+    box-sizing: border-box;
+    box-shadow: 0 2px 2px 0 rgba(0,0,0,.14), 0 1px 5px 0 rgba(0,0,0,.12), 0 3px 1px -2px rgba(0,0,0,.2);
+    max-width: 100%;
+    border-radius: .2rem;
+}
+
+.md-fenced-code-tabs {
+    display: flex;
+    position: relative;
+    flex-wrap: wrap;
+    width: 100%;
+}
+
+.md-fenced-code-tabs input {
+    position: absolute;
+    opacity: 0;
+}
+
+.md-fenced-code-tabs label {
+    width: auto;
+    cursor: pointer;
+    font-size: 1.28rem;
+    padding: 1.2rem 1.6rem;
+}
+
+.md-fenced-code-tabs input:checked + label {
+    color: #03a9f4;
+    border-bottom: 2px solid #03a9f4;
+}
+
+.md-fenced-code-tabs .code-tabpanel {
+    display: none;
+    width: 100%;
+    order: 99;
+}
+
+.md-fenced-code-tabs input:checked + label + .code-tabpanel {
+    display: block;
+}
+
+.md-fenced-code-tabs pre,
+.md-fenced-code-tabs .codehilite {
+    width: 100%;
+    margin: 0px;
+    padding-top: 5px;
+    padding-bottom: 5px;
+}

docs/src/contributing.md

@@ -0,0 +1,23 @@
+:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: It's people like you that make the open source community such a great community! 😊
+
+Any type of contribution is welcome, not only code. You can help with 
+
+- **QA**: file bug reports, the more details you can give the better (e.g. screenshots with the console open)
+- **Code**: take a look at the [open issues](https://github.com/yacir/markdown-fenced-code-tabs/issues). Even if you can't write code, commenting on them, showing that you care about a given issue matters. It helps us triage them.
+
+## Your First Contribution
+
+Working on your first Pull Request? You can learn how from this *free* series, [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github).
+
+## Submitting code
+
+Any code change should be submitted as a pull request. The description should explain what the code does and give steps to execute it. The pull request should also contain tests.
+
+## Code review process
+
+The bigger the pull request, the longer it will take to review and merge. Try to break down large pull requests in smaller chunks that are easier to review and merge.
+It is also always helpful to have some context for your pull request. What was the purpose? Why does it matter to you?
+
+## Questions
+
+If you have any questions or found a bug in the source code, create an [issue](https://github.com/yacir/markdown-fenced-code-tabs/issues) (protip: do a quick search first to see if someone else didn't ask the same question before!).

docs/src/index.md

@@ -0,0 +1,113 @@
+# Code Tabs Extension <small>Documentation</small>
+
+!!! important ""
+    Migrating from an older version? Check out our [Release notes](release-notes.md).
+
+## Overview
+
+**Code Tabs** is an extension that generates a HTML structure for consecutive fenced code blocks content. It provides four features:
+
+- [X] The ability to choose the HTML template.
+- [X] The ability to specify custom label for a tab.
+- [X] The ability to enable tab generation for a single fenced code block.
+- [X] The ability to specify the css class for the tab active state.
+
+Example:
+
+```` markdown
+``` c
+printf("HELLO WORLD!");
+```
+
+``` java 
+System.out.println("HELLO WORLD!");
+```
+
+``` python
+print("HELLO WORLD!")
+```
+````
+
+Result:
+
+``` c
+printf("HELLO WORLD!");
+```
+
+``` java 
+System.out.println("HELLO WORLD!");
+```
+
+``` python
+print("HELLO WORLD!")
+```
+
+## Installation
+
+Installation is easy with pip:
+
+``` sh
+pip install markdown-fenced-code-tabs
+``` 
+
+If you want to manually install it, run `python setup.py build` and `python setup.py install`. You should be able to access the extensions in Python Markdown.
+
+If you would like to modify the code, you can install it via: `python setup.py develop`. This method will allow you to instantly see your changes without reinstalling.
+
+## Usage 
+
+In order to enable the extension just add it to your **markdown_extensions** list:
+
+``` yaml
+markdown_extensions:
+  - markdown_fenced_code_tabs
+```
+
+This will add the extension with the default [options](#options). To configure them: 
+
+``` yaml
+markdown_extensions:
+  - markdown_fenced_code_tabs:
+      single_block_as_tab: False
+      active_class: 'active'
+      template: 'default'
+```
+
+!!! important
+    If you choose the `default` template you wiLl have to add the needed **css** as explained in the [templates documentation](templates.md). 
+
+### Label customization
+
+By default the tab label is the language of the code block but it can be customized by passing the title to the `fct_label` argument placed right after the language identifier.
+
+Example:
+
+```` markdown
+``` python fct_label="Python 2"
+print "Bonjour" 
+```
+
+``` python fct_label="Python 3"
+print("Bonjour")
+```
+````
+
+Result:
+
+``` python fct_label="Python 2"
+print "Bonjour" 
+```
+
+``` python fct_label="Python 3"
+print("Bonjour")
+```
+
+## Options
+
+The following options are provided to configure the output:
+
+Option                         | Type | Default | Description
+------------------------------ | -----| --------| -----------
+`single_block_as_tab`          | bool | `False` | Renders a single fenced code block as a tab.
+`active_class`                 | string | `active` | Class name is applied to the active tab. 
+`template`                     | string | `default`| A string that specifies which HTML template should be used `default`, `bootstrap3`, or `bootstrap4`.

docs/src/licence.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2017-present [Yassir Barchi]([email protected])
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.