fix sphinx docs

README.md

@@ -38,9 +38,7 @@ If you want to do this stuff in a fast and easy way, this library is for ya.
 ```python
 import os
 from mutagen.mp3 import MP3
-
 my_folder = "path to folder containing songs"
-
 for root, dirs, files in os.walk(my_folder):
     for file in files:
         audio = MP3(file)
@@ -52,9 +50,7 @@ for root, dirs, files in os.walk(my_folder):
 ```python
 from hal.files.models.system import ls_recurse
 from hal.files.models.audio import MP3Song
-
 my_folder = "path to folder containing songs"
-
 for file in ls_recurse(my_folder):
     MP3Song(file).set_artist("An example")
 ```
@@ -65,7 +61,6 @@ for file in ls_recurse(my_folder):
 ```python
 import numpy as np
 import matplotlib.pyplot as plt
-
 x = np.arange(1., 100.)
 y = np.sin(x)
 plt.plot(x, y)
@@ -76,7 +71,6 @@ plt.show()
 ```python
 import numpy as np
 from hal.charts.plotter import Plot2d
-
 Plot2d().plot(np.sin, 1, 100, 100)
 ```
 
@@ -89,10 +83,8 @@ No easy way that I know of
 #### Using `pyhal`
 ```python
 from hal.internet.services.youtube import YoutubeChannel
-
 video_url = "my awesome video of an awesome channel"
 channel_feed = YoutubeChannel.get_feed_url_from_video(video_url)
-
 # or if you know the name
 channel_name = "my awesome channel"
 channel_feed = YoutubeChannel(channel_name).get_feed_url()
@@ -109,7 +101,7 @@ Different ways, all equals
 - ```$ make install```
 
 ### via `pip`
-- ```$ pip3 install PyHal``` via [pip](https://pypi.org/project/PyHal/)
+- ```$ pip3 install PyHal```
 - ```$ make pip-install```
 
 ### fast install
@@ -155,4 +147,4 @@ Suggestions and improvements are [welcome](https://github.com/sirfoga/pyhal/issu
 
 
 ## License
-<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
+<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg"></a>

docs/Makefile

@@ -17,4 +17,6 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	rm -rf _build
+	rm -rf source
+	sphinx-apidoc -o source/ ../hal
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -97,7 +97,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.

docs/index.rst

@@ -4,114 +4,221 @@
    contain the root `toctree` directive.
 
 Hal: Your swiss knife to perform fast and easy pythonic stuff
-=================================
+=============================================================
 
-Release v\ |version| (:ref:`Installation <install>`)
+Release v\ |version|
 
-.. image:: https://img.shields.io/pypi/l/requests.svg
-    :target: https://pypi.org/project/requests/
 
-.. image:: https://img.shields.io/pypi/wheel/requests.svg
-    :target: https://pypi.org/project/requests/
+.. image:: https://img.shields.io/badge/License-MIT-blue.svg
+   :target: https://opensource.org/licenses/MIT
 
-.. image:: https://img.shields.io/pypi/pyversions/requests.svg
-    :target: https://pypi.org/project/requests/
+.. image:: https://badge.fury.io/py/PyHal.svg
+   :target: https://pypi.org/project/PyHal/
 
-.. image:: https://codecov.io/github/requests/requests/coverage.svg?branch=master
-    :target: https://codecov.io/github/requests/requests
-    :alt: codecov.io
-
-.. image:: https://img.shields.io/badge/Say%20Thanks!-🦉-1EAEDB.svg
-    :target: https://saythanks.io/to/kennethreitz
+.. image:: https://img.shields.io/badge/Python-3.6-blue.svg
+   :target: https://www.python.org/download/releases/3
 
+.. image:: https://codecov.io/github/sirfoga/pyhal/coverage.svg?branch=master
+   :target: https://codecov.io/github/rsirfoga/pyhal
 
 -------------------
 
-**Behold, the power of Hal**::
 
-    >>> r = requests.get('https://api.github.com/user', auth=('user', 'pass'))
-    >>> r.status_code
-    200
-    >>> r.headers['content-type']
-    'application/json; charset=utf8'
-    >>> r.encoding
-    'utf-8'
-    >>> r.text
-    u'{"type":"User"...'
-    >>> r.json()
-    {u'private_gists': 419, u'total_private_repos': 77, ...}
+Table of contents
+-----------------
 
-See `similar code, sans pyhal <https://gist.github.com/973705>`_.
+* `Introduction`_
+* `Installation`_
+* `Contribute`_
+* `Authors`_
+* `Thanks`_
+* `License`_
 
+API reference
+-------------
 
+* `Hal`_
+* `Alphabetical list`_
 
-Table of contents
---------------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Behold, the power of Hal
+------------------------
 
+Edit songs tags
+~~~~~~~~~~~~~~~
 
-The User Guide
---------------
+Classic way
+^^^^^^^^^^^
 
-This part of the documentation, which is mostly prose, begins with some
-background information about Requests, then focuses on step-by-step
-instructions for getting the most out of Requests.
+.. code:: python
 
-.. toctree::
-   :maxdepth: 2
+    >>> import os
+    >>> from mutagen.mp3 import MP3
+    >>> my_folder = "path to folder containing songs"
+    >>> for root, dirs, files in os.walk(my_folder):
+    >>>     for file in files:
+    >>>         audio = MP3(file)
+    >>>         audio["artist"] = "An example"
+    >>>         audio.save()
 
-   user/intro
-   user/install
-   user/quickstart
-   user/advanced
-   user/authentication
+Using ``pyhal``
+^^^^^^^^^^^^^^^
 
+.. code:: python
 
-The Community Guide
--------------------
+    >>> from hal.files.models.system import ls_recurse
+    >>> from hal.files.models.audio import MP3Song
+    >>> my_folder = "path to folder containing songs"
+    >>> for file in ls_recurse(my_folder):
+    >>>     MP3Song(file).set_artist("An example")
+
+Plot data
+~~~~~~~~~
+
+.. _classic-way-1:
+
+Classic way
+^^^^^^^^^^^
+
+.. code:: python
+
+    >>> import numpy as np
+    >>> import matplotlib.pyplot as plt
+    >>> x = np.arange(1., 100.)
+    >>> y = np.sin(x)
+    >>> plt.plot(x, y)
+    >>> plt.show()
+
+.. _using-pyhal-1:
+
+Using ``pyhal``
+^^^^^^^^^^^^^^^
+
+.. code:: python
+
+    >>> import numpy as np
+    >>> from hal.charts.plotter import Plot2d
+    >>> Plot2d().plot(np.sin, 1, 100, 100)
+
+Get YouTube RSS feed of channel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _classic-way-2:
+
+Classic way
+^^^^^^^^^^^
+
+No easy way that I know of
+
+.. _using-pyhal-2:
+
+Using ``pyhal``
+^^^^^^^^^^^^^^^
+
+.. code:: python
+
+    >>> from hal.internet.services.youtube import YoutubeChannel
+    >>> video_url = "my awesome video of an awesome channel"
+    >>> channel_feed = YoutubeChannel.get_feed_url_from_video(video_url)
+    >>> # or if you know the name
+    >>> channel_name = "my awesome channel"
+    >>> channel_feed = YoutubeChannel(channel_name).get_feed_url()
+
+
+Install
+-------
+
+Different ways, all equals
+
+via ``pipenv``
+~~~~~~~~~~~~~~
+
+-  ``$ pipenv install .``
+-  ``$ make install``
+
+via ``pip``
+~~~~~~~~~~~
+
+-  ``$ pip3 install PyHal``
+-  ``$ make pip-install``
+
+fast install
+~~~~~~~~~~~~
+
+-  ``make fast-init`` *just copies source files to distitribution files
+   … run it only if you’re sure about dependencies*
+
+.. _pip: https://pypi.org/project/PyHal/
+
+
+Contributing and feedback
+-------------------------
+
+0. `open an issue`_
+1. `fork`_ this repository
+2. create your feature branch (``git checkout -b my-new-feature``)
+3. commit your changes (``git commit -am 'Added my new feature'``)
+4. publish the branch (``git push origin my-new-feature``)
+5. `open a PR`_
+
+Suggestions and improvements are `welcome`_!
+
+Authors
+-------
 
-This part of the documentation, which is mostly prose, details the
-Requests ecosystem and community.
++----------------------+
+| |sirfoga|            |
++======================+
+| `Stefano Fogarollo`_ |
++----------------------+
 
-.. toctree::
-   :maxdepth: 2
+Thanks to
+---------
 
-   community/sponsors
-   community/recommended
-   community/faq
-   community/out-there
-   community/support
-   community/vulnerabilities
-   community/updates
-   community/release-process
+-  `Kenneth Reitz`_
 
-The API Documentation / Guide
------------------------------
+License
+-------
+.. image:: https://img.shields.io/badge/License-MIT-blue.svg
+   :target: https://opensource.org/licenses/MIT
 
-If you are looking for information on a specific function, class, or method,
-this part of the documentation is for you.
+The MIT License (MIT)
 
-.. toctree::
-   :maxdepth: 2
+Copyright (c) Stefano Fogarollo
 
-   api
+    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 Contributor Guide
----------------------
+    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.
 
-If you want to contribute to the project, this part of the documentation is for
-you.
 
-.. toctree::
-   :maxdepth: 3
+.. _open an issue: https://github.com/sirfoga/pyhal/issues/new
+.. _fork: https://github.com/sirfoga/pyhal/fork
+.. _open a PR: https://github.com/sirfoga/pyhal/compare
+.. _welcome: https://github.com/sirfoga/pyhal/issues
+.. _Stefano Fogarollo: https://sirfoga.github.io
+.. _Kenneth Reitz: https://github.com/kennethreitz
 
-   dev/contributing
-   dev/philosophy
-   dev/todo
-   dev/authors
+.. |sirfoga| image:: https://avatars0.githubusercontent.com/u/14162628?s=128&v=4
+   :target: https://github.com/sirfoga
 
-.. todo add thanks to section (mirror README.md)
+.. _Introduction: #behold-the-power-of-hal
+.. _Installation: #install
+.. _Contribute: #contributing-and-feedback
+.. _Authors: #authors
+.. _Thanks: #thanks-to
+.. _License: #license
+.. _Hal: source/hal.html
+.. _Alphabetical list: genindex.html