Merge pull request #20 from fastapi-mvc/improve_docs

Improve documentation
fastapi-mvc · Oct 4, 2022 · 48384fe · 48384fe
2 parents 355c0cf + 18461df
commit 48384fe
Show file tree

Hide file tree

Showing 9 changed files with 529 additions and 374 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 This file documents changes to [fastapi-mvc/cookiecutter](https://github.com/fastapi-mvc/cookiecutter). The release numbering uses [semantic versioning](http://semver.org).
 
+## Unreleased
+
+### Internal
+
+* Extend project documentation [#21](https://github.com/fastapi-mvc/cookiecutter/issues/21). PR [#20](https://github.com/fastapi-mvc/cookiecutter/pull/20)
+
 ## 0.2.0 (29.09.2022)
 
 ### Features

diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py
@@ -76,6 +76,7 @@ def set_nix():
                 "overlay.nix",
                 "Nix.mk",
                 ".github/workflows/nix.yml",
+                "docs/nix.rst",
             ]
         )
 

diff --git a/{{cookiecutter.folder_name}}/README.md b/{{cookiecutter.folder_name}}/README.md
diff --git a/{{cookiecutter.folder_name}}/docs/deployment.rst b/{{cookiecutter.folder_name}}/docs/deployment.rst
@@ -0,0 +1,7 @@
+Deployment
+==========
+
+Will be added soon: `issue <https://github.com/fastapi-mvc/fastapi-mvc/issues/81>`__
+
+In the meantime, `FastAPI deployment documentation <https://fastapi.tiangolo.com/deployment/>`__ might be helpful.
+And, if you shall have any questions feel free to issue them `here <https://github.com/fastapi-mvc/fastapi-mvc/issues/new?assignees=&labels=question&template=question.md&title=>`__.
diff --git a/{{cookiecutter.folder_name}}/docs/index.rst b/{{cookiecutter.folder_name}}/docs/index.rst
@@ -1,15 +1,129 @@
 Documentation
 =============
 
-.. _fastapi-mvc:
-    https://github.com/fastapi-mvc/fastapi-mvc
-
 --------------
 
-**This project was generated with fastapi-mvc**
+**This project was generated with:** `fastapi-mvc <https://github.com/fastapi-mvc/fastapi-mvc>`__
 
 --------------
 
+Quickstart
+~~~~~~~~~~
+
+If You want to go easy way and use provided virtualized environment You'll need to have installed:
+
+* rsync
+* Vagrant `(How to install vagrant) <https://www.vagrantup.com/downloads>`__
+* (Optional) Enabled virtualization in BIOS
+
+First run ``vagrant up`` in project root directory and enter virtualized environment using ``vagrant ssh``
+Then run following commands to bootstrap local development cluster exposing ``fastapi-mvc`` application.
+
+.. code-block:: bash
+
+    cd /syncd
+    make dev-env
+
+.. note::
+    This process may take a while on first run.
+
+Once development cluster is up and running you should see summary listing application address:
+
+.. code-block:: bash
+
+    Kubernetes cluster ready
+
+    fastapi-mvc available under: http://{{cookiecutter.folder_name}}.192.168.49.2.nip.io/
+
+    You can delete dev-env by issuing: minikube delete
+
+.. note::
+    Above address may be different for your installation.
+
+    Provided virtualized env doesn't have port forwarding configured which means, that bootstrapped application stack in k8s won't be accessible on Host OS.
+
+Deployed application stack in Kubernetes:
+{%- if cookiecutter.redis == "yes" %}
+
+.. code-block:: bash
+
+    vagrant@ubuntu-focal:/syncd$ make dev-env
+    ...
+    ...
+    ...
+    Kubernetes cluster ready
+    FastAPI available under: http://{{cookiecutter.folder_name}}.192.168.49.2.nip.io/
+    You can delete dev-env by issuing: make clean
+    vagrant@ubuntu-focal:/syncd$ kubectl get all -n {{cookiecutter.folder_name}}
+    NAME                                                     READY   STATUS    RESTARTS   AGE
+    pod/{{cookiecutter.folder_name}}-7f4dd8dc7f-p2kr7                1/1     Running   0          55s
+    pod/rfr-redisfailover-persistent-keep-0                  1/1     Running   0          3m39s
+    pod/rfr-redisfailover-persistent-keep-1                  1/1     Running   0          3m39s
+    pod/rfr-redisfailover-persistent-keep-2                  1/1     Running   0          3m39s
+    pod/rfs-redisfailover-persistent-keep-5d46b5bcf8-2r7th   1/1     Running   0          3m39s
+    pod/rfs-redisfailover-persistent-keep-5d46b5bcf8-6kqv5   1/1     Running   0          3m39s
+    pod/rfs-redisfailover-persistent-keep-5d46b5bcf8-sgtvv   1/1     Running   0          3m39s
+
+    NAME                                        TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)     AGE
+    service/{{cookiecutter.folder_name}}                ClusterIP   10.110.42.252   <none>        8000/TCP    56s
+    service/rfs-redisfailover-persistent-keep   ClusterIP   10.110.4.24     <none>        26379/TCP   3m39s
+
+    NAME                                                READY   UP-TO-DATE   AVAILABLE   AGE
+    deployment.apps/{{cookiecutter.folder_name}}                1/1     1            1           55s
+    deployment.apps/rfs-redisfailover-persistent-keep   3/3     3            3           3m39s
+
+    NAME                                                           DESIRED   CURRENT   READY   AGE
+    replicaset.apps/{{cookiecutter.folder_name}}-7f4dd8dc7f                1         1         1       55s
+    replicaset.apps/rfs-redisfailover-persistent-keep-5d46b5bcf8   3         3         3       3m39s
+
+    NAME                                                 READY   AGE
+    statefulset.apps/rfr-redisfailover-persistent-keep   3/3     3m39s
+
+    NAME                                                                  AGE
+    redisfailover.databases.spotahome.com/redisfailover-persistent-keep   3m39s
+    vagrant@ubuntu-focal:/syncd$ curl http://{{cookiecutter.folder_name}}.192.168.49.2.nip.io/api/ready
+    {"status":"ok"}
+
+{%- else %}
+
+.. code-block:: bash
+
+    vagrant@ubuntu-focal:/syncd$ make dev-env
+    ...
+    ...
+    ...
+    Kubernetes cluster ready
+    FastAPI available under: http://{{cookiecutter.folder_name}}.192.168.49.2.nip.io/
+    You can delete dev-env by issuing: make clean
+    vagrant@ubuntu-focal:/syncd$ kubectl get all -n {{cookiecutter.folder_name}}
+    NAME                        READY   STATUS    RESTARTS   AGE
+    pod/{{cookiecutter.folder_name}}-649966bb7f-r694l   1/1     Running   0          114s
+
+    NAME           TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)    AGE
+    service/{{cookiecutter.folder_name}}   ClusterIP   10.97.16.46   <none>        8000/TCP   114s
+
+    NAME                   READY   UP-TO-DATE   AVAILABLE   AGE
+    deployment.apps/{{cookiecutter.folder_name}}   1/1     1            1           114s
+
+    NAME                              DESIRED   CURRENT   READY   AGE
+    replicaset.apps/{{cookiecutter.folder_name}}-649966bb7f   1         1         1       114s
+    vagrant@ubuntu-focal:/syncd$ curl http://{{cookiecutter.folder_name}}.192.168.49.2.nip.io/api/ready
+    {"status":"ok"}
+
+{%- endif %}
+Documentation
+-------------
+
+This part of the documentation guides you through all of the features and usage.
+
+.. toctree::
+   :maxdepth: 2
+
+   install
+   {% if cookiecutter.redis == "yes" %}nix{% endif %}
+   usage
+   deployment
+
 API Reference
 -------------
 
@@ -29,4 +143,3 @@ Miscellaneous Pages
 
    license
    CHANGELOG.md
-
diff --git a/{{cookiecutter.folder_name}}/docs/install.rst b/{{cookiecutter.folder_name}}/docs/install.rst
@@ -0,0 +1,64 @@
+Installation
+============
+
+Application
+-----------
+
+Prerequisites:
+
+* Python 3.7 or later `(How to install python) <https://docs.python-guide.org/starting/installation/>`__
+* make
+* (optional) curl
+* (optional) Poetry `(How to install poetry) <https://python-poetry.org/docs/#installation>`__
+
+To install fastapi-mvc from source first clone the repository and use ``make install`` target:
+
+.. code-block:: bash
+
+    make install
+
+By default ``make install`` target will search first for ``python3`` then ``python`` executable in your ``PATH``.
+If needed this can be overridden by ``PYTHON`` environment variable.
+
+.. code-block:: bash
+
+    export PYTHON=/path/to/my/python
+    make install
+
+Lastly if Poetry is not found in its default installation directory (${HOME}/.local/share/pypoetry) this target will install it for you.
+However, one can always point to existing/customize Poetry installation with `environment variables <https://python-poetry.org/docs/configuration/#using-environment-variables>`__:
+
+.. code-block:: bash
+
+    export POETRY_HOME=/custom/poetry/path
+    export POETRY_CACHE_DIR=/custom/poetry/path/cache
+    export POETRY_VIRTUALENVS_IN_PROJECT=true
+    make install
+
+Or using Poetry directly, should you choose:
+
+.. code-block:: bash
+
+    poetry install
+
+Infrastructure
+--------------
+
+Prerequisites:
+
+* make
+* gcc
+* golang
+* minikube version 1.22.0 `(How to install minikube) <https://minikube.sigs.k8s.io/docs/start>`__
+* helm version 3.0.0 or higher `(How to install helm) <https://helm.sh/docs/intro/install>`__
+* kubectl version 1.16 up to 1.20.8 `(How to install kubectl) <https://kubernetes.io/docs/tasks/tools/install-kubectl-linux>`__
+* Container runtime interface.
+
+.. note::
+    Makefile dev-env target uses docker for minikube, for other CRI you'll need to modify this line in ``build/dev-env.sh`` ``MINIKUBE_IN_STYLE=0 minikube start --driver=docker 2>/dev/null``
+
+To bootstrap local minikube Kubernetes cluster exposing ``{{cookiecutter.folder_name}}`` application run:
+
+.. code-block:: bash
+
+    make dev-env
diff --git a/{{cookiecutter.folder_name}}/docs/nix.rst b/{{cookiecutter.folder_name}}/docs/nix.rst
@@ -0,0 +1,38 @@
+Using Nix
+=========
+
+Installation
+------------
+
+Prerequisites:
+
+* Nix 2.8.x or later installed `(How to install Nix) <https://nixos.org/download.html>`__
+
+First configure Nix channel if needed:
+
+.. code-block:: bash
+
+    nix-channel --add https://nixos.org/channels/nixos-22.05
+    nix-channel --update
+
+Next install make via Nix:
+
+.. code-block:: bash
+
+    nix-env --install gnumake
+    # If you do not want to install make to your profile, one can always use it ad-hoc via nix-shell
+    nix-shell -p gnumake
+
+Lastly, use ``make install`` target:
+
+.. code-block:: bash
+
+    make install
+    # Or
+    nix-shell -p gnumake --run "make install"
+
+Or using Nix directly, should you choose:
+
+.. code-block:: bash
+
+    nix-build -E 'with import <nixpkgs> { overlays = [ (import ./overlay.nix) ]; }; callPackage ./editable.nix {python = pkgs.python310; poetry2nix = pkgs.poetry2nix;}'