Merge pull request #28 from juneHQ/vinayak/2024-12-27-add-docs

Add docs

.readthedocs.yaml

@@ -20,4 +20,3 @@ sphinx:
 # python:
 #    install:
 #    - requirements: docs/requirements.txt
-

README.md

@@ -8,7 +8,7 @@
 [![image](https://img.shields.io/pypi/l/houseplant.svg)](https://pypi.org/project/houseplant/)
 [![image](https://img.shields.io/pypi/pyversions/houseplant.svg)](https://pypi.org/project/houseplant/)
 
-**Houseplant** is a CLI tool that helps you manage database migrations for ClickHouse!
+**Houseplant** is a CLI tool that helps you manage database migrations for ClickHouse.
 
 ---
 

docs/conf.py

@@ -20,9 +20,13 @@
 import os
 import sys
 
+import tomli
+
 sys.path.insert(0, os.path.abspath(".."))
 
-import houseplant
+# Read version from pyproject.toml
+with open("../pyproject.toml", "rb") as f:
+    pyproject = tomli.load(f)
 
 # -- General configuration ---------------------------------------------
 
@@ -32,7 +36,11 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -56,16 +64,16 @@
 # the built documents.
 #
 # The short X.Y version.
-version = houseplant.__version__
+version = pyproject["project"]["version"]
 # The full version, including alpha/beta/rc tags.
-release = houseplant.__version__
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -86,11 +94,22 @@
 #
 html_theme = "alabaster"
 
+html_logo = "_static/logo.png"
+
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    "logo_text_align": "center",
+    "github_user": "juneHQ",
+    "github_repo": "houseplant",
+    "github_button": True,
+    "github_type": "star",
+    "fixed_sidebar": True,
+    "show_powered_by": False,
+    "show_relbars": True,
+}
 
 # 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,
@@ -148,7 +167,7 @@
         "houseplant Documentation",
         author,
         "houseplant",
-        "One line description of project.",
+        "Database Migrations for ClickHouse",
         "Miscellaneous",
     ),
 ]

docs/index.rst

@@ -1,17 +1,61 @@
-Welcome to houseplant's documentation!
-======================================
+Houseplant: Database Migrations for ClickHouse
+==============================================
+
+.. image:: https://img.shields.io/pypi/v/houseplant.svg
+   :target: https://pypi.python.org/pypi/houseplant
+
+.. image:: https://img.shields.io/pypi/l/houseplant.svg
+   :target: https://pypi.org/project/houseplant/
+
+.. image:: https://img.shields.io/pypi/pyversions/houseplant.svg
+   :target: https://pypi.org/project/houseplant/
+
+Houseplant is a CLI tool that helps you manage database migrations for ClickHouse.
+
+Here's how you can manage your ClickHouse migrations:
+
+.. code-block:: console
+
+   $ houseplant init
+   ✨ Project initialized successfully!
+
+   $ houseplant generate "add events"
+   ✨ Generated migration: ch/migrations/20240101000000_add_events.yml
+
+   $ houseplant migrate:status
+   Database: june_development
+
+   ┏━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+   ┃ Status ┃ Migration ID   ┃ Migration Name ┃
+   ┡━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
+   │   up   │ 20240101000000 │ add events     │
+   └────────┴────────────────┴────────────────┘
+
+   $ houseplant migrate
+   ✓ Applied migration 20241121003230_add_events.yml
+
+   $ houseplant migrate:up VERSION=20241121003230
+   ✓ Applied migration 20241121003230_add_events.yml
+
+   $ houseplant migrate:down VERSION=20241121003230
+   ✓ Rolled back migration 20241121003230_add_events.yml
+
+Why Houseplant?
+---------------
+
+- **Schema Management**: Houseplant automatically tracks and manages your ClickHouse schema changes, making it easy to evolve your data model over time
+- **Developer Experience**: Write migrations in YAML format, making them easy to read, review, and maintain
+- **Environment Support**: Different configurations for development, testing, and production environments
+- **Rich CLI**: Comes with an intuitive command-line interface for all migration operations
+
+The User Guide
+--------------
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
-   readme
-   installation
+   install
    usage
-   modules
-   contributing
-   authors
-   history
 
 Indices and tables
 ==================

docs/install.rst

@@ -0,0 +1,28 @@
+.. highlight:: shell
+
+============
+Installation
+============
+
+You can install Houseplant using pip:
+
+.. code-block:: console
+
+    $ pip install houseplant
+
+From Source
+-----------
+
+You can clone the `Github repo`_:
+
+.. code-block:: console
+
+    $ git clone git://github.com/juneHQ/houseplant
+
+And then, you can install it with:
+
+.. code-block:: console
+
+    $ pip install -e .
+
+.. _Github repo: https://github.com/yourusername/houseplant