Update docs

Close #70

Author: stsewd

Makefile

@@ -13,6 +13,9 @@ format:
 docs:
 	python -m nox -r -s docs
 
+serve-docs:
+	python -m nox -r -s docs -- --live
+
 clean:
 	rm -rf dist/
 	rm -rf build/
@@ -22,4 +25,4 @@ publish: clean
 	python setup.py sdist bdist_wheel
 	python -m twine upload dist/*
 
-.PHONY: tests lint format docs clean publish coverage
+.PHONY: tests lint format docs serve-docs clean publish coverage

README.md

@@ -9,26 +9,6 @@ Python interactive tutorial in your terminal.
 
 _Learn, Imagine, Repeat, Analyze_
 
-**This program is still under development, many things may change!**
+**This project is still under development, many things may and will change!**
 
-## Features
-
-- Command line tutorial (100% text)
-- Multi platform
-- Easy to install
-- Content for all levels
-- Autocomplete (program arguments)
-- Easy to add new tutorials
-- Multi-languages (i18n)
-- Edit the code with your preferred editor
-- Save your advance
-
-## No-Features
-
-- It is not a web tutorial
-- No mobile support
-- It does not have multi-user support
-- It is not an editor or IDE for Python
-- Does not support other programming languages
-- Not a replacement for Jupyter Notebook
-- It is not a reference document or book
+Check the docs at <https://lira.python.ec>.

docs/config.rst

@@ -0,0 +1,46 @@
+Configuration
+=============
+
+The configuration file is located at ``~/.config/lira/config.yaml`` on UNIX-like systems,
+and at ``~/AppData/Local/config.yaml`` on Windows systems.
+This is how it looks like
+
+.. code-block:: yaml
+
+   books:
+     - lira.books.intro
+     - example/
+
+.. note::
+
+   Lira follows the XDG_ base directory specification.
+
+   .. _XDG: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+
+
+All supported settings are document below.
+
+books
+-----
+
+List of books, each book can be a dotted path to the module of the book,
+or a local path to the directory of the book
+(it can be a relative path to the config file).
+
+.. code-block:: yaml
+   books:
+      # A dotted path to a module
+      - lira.books.intro
+
+      # An absolute local path
+      - ~/local/path/to/book/
+
+      # A relative path to the config file
+      - relative/path
+
+Defaults to:
+
+.. code-block:: yaml
+
+   books:
+     - lira.books.intro

docs/development.rst

@@ -1,6 +1,9 @@
 Development
 ===========
 
+Contributing
+------------
+
 **Thanks** for the interest in contributing to Lira!
 
 Requirements:
@@ -57,3 +60,40 @@ and see if the linter, tests, and coverage are passing.
    make lint
    make tests
    make coverage
+
+Roadmap
+-------
+
+Goals
+~~~~~
+
+- Command line tutorial (100% text)
+- Multi platform
+- Easy to install
+- Content for all levels
+- Autocomplete (program arguments)
+- Easy to add new tutorials
+- Multi-languages (i18n)
+- Edit the code with your favorite editor
+- Save your advance
+
+Non-Goals
+~~~~~~~~~
+
+- It is not a web tutorial
+- No mobile support
+- It does not have multi-user support
+- It is not an editor or IDE for Python
+- Does not support other languages
+- Not a replacement for Jupyter Notebook
+- It is not a reference document or book
+
+Random ideas for the future
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Multiple themes support
+- Plugins
+- Share your score
+- Expand to other types of tutorials (physics, math, statistics)
+- Against the clock mode
+- Quiz mode

docs/index.rst

@@ -4,49 +4,35 @@ Lira
 Python interactive tutorial in your terminal.
 This is a project from the `Python Ecuador <https://python.ec/>`__ community.
 
-*Learn, Imagine, Repeat, Analyze*
+*Learn, Imagine, Repeat, Analyze*.
 
 .. note::
 
-   This program is still under development, many things may change!
+   This project is still under development, many things may and will change!
+
+Quickstart
+----------
+
+Install Lira with ``pip``:
+
+.. code-block:: bash
+
+   python -m pip install --user lira
+
+Run ``lira``:
+
+.. code-block:: bash
+
+   lira
+   # or
+   python -m lira
+
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
+   config.rst
    development.rst
    modules/index.rst
-
-Features
---------
-
-- Command line tutorial (100% text)
-- Multi platform
-- Easy to install
-- Content for all levels
-- Autocomplete (program arguments)
-- Easy to add new tutorials
-- Multi-languages
-- Edit the code with your favorite editor
-- Save your advance
-
-No-Features
------------
-
-- It is not a web tutorial
-- No mobile support
-- It does not have multi-user support
-- It is not an editor or IDE for Python
-- Does not support other languages
-- Not a replacement for Jupyter Notebook
-- It is not a reference document or book
-
-Random ideas for the future
----------------------------
-
-- Multiple themes support
-- Plugins
-- Share your score
-- Expand to other types of tutorials (physics, math, statistics)
-- Against the clock mode
-- Quiz mode

noxfile.py

@@ -42,5 +42,12 @@ def format(session):
 @nox.session
 def docs(session):
     session.install("-e", ".[docs]")
+    live_update = session.posargs and session.posargs[0] == "--live"
+    if live_update:
+        session.install("sphinx-autobuild")
+
     session.cd("docs")
-    session.run("sphinx-build", "-b", "html", "-W", ".", "_build/html")
+    if live_update:
+        session.run("sphinx-autobuild", ".", "_build/html")
+    else:
+        session.run("sphinx-build", "-b", "html", "-W", ".", "_build/html")