diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/Makefile | 29 | ||||
-rw-r--r-- | docs/__init__.py | 1 | ||||
-rw-r--r-- | docs/conf.py | 64 | ||||
-rw-r--r-- | docs/howto.rst | 38 | ||||
-rw-r--r-- | docs/index.rst | 24 | ||||
-rw-r--r-- | docs/make.bat | 46 | ||||
-rw-r--r-- | docs/pycharm/configuration.rst | 70 | ||||
-rw-r--r-- | docs/pycharm/images/1.png | bin | 67153 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/2.png | bin | 15163 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/3.png | bin | 181106 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/4.png | bin | 113084 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/7.png | bin | 6284 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/8.png | bin | 19800 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/f1.png | bin | 254645 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/f2.png | bin | 234376 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/f3.png | bin | 235846 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/f4.png | bin | 226939 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/issue1.png | bin | 43350 -> 0 bytes | |||
-rw-r--r-- | docs/pycharm/images/issue2.png | bin | 11625 -> 0 bytes | |||
-rw-r--r-- | docs/users.rst | 15 |
20 files changed, 0 insertions, 287 deletions
diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 6957700..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,29 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = ./_build -APP = /app - -.PHONY: help livehtml apidocs Makefile - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c . - -# Build, watch and serve docs with live reload -livehtml: - sphinx-autobuild -b html --host 0.0.0.0 --port 9000 --watch $(APP) -c . $(SOURCEDIR) $(BUILDDIR)/html - -# Outputs rst files from django application code -apidocs: - sphinx-apidoc -o $(SOURCEDIR)/api $(APP) - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c . diff --git a/docs/__init__.py b/docs/__init__.py deleted file mode 100644 index 8772c82..0000000 --- a/docs/__init__.py +++ /dev/null @@ -1 +0,0 @@ -# Included so that Django's startproject comment runs against the docs directory diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 3dc1bc6..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,64 +0,0 @@ -# ruff: noqa -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. - -import os -import sys -import django - -if os.getenv("READTHEDOCS", default=False) == "True": - sys.path.insert(0, os.path.abspath("..")) - os.environ["DJANGO_READ_DOT_ENV_FILE"] = "True" - os.environ["USE_DOCKER"] = "no" -else: - sys.path.insert(0, os.path.abspath("/app")) -os.environ["DATABASE_URL"] = "sqlite:///readthedocs.db" -os.environ["CELERY_BROKER_URL"] = os.getenv("REDIS_URL", "redis://redis:6379") -os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.local") -django.setup() - -# -- Project information ----------------------------------------------------- - -project = "pyblackbird-cc" -copyright = """2024, Matthew Lemon""" -author = "Matthew Lemon" - - -# -- General configuration --------------------------------------------------- - -# 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.napoleon", -] - -# Add any paths that contain templates here, relative to this directory. -# templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "alabaster" - -# 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"] diff --git a/docs/howto.rst b/docs/howto.rst deleted file mode 100644 index 5858a25..0000000 --- a/docs/howto.rst +++ /dev/null @@ -1,38 +0,0 @@ -How To - Project Documentation -====================================================================== - -Get Started ----------------------------------------------------------------------- - -Documentation can be written as rst files in `alphabetlearning/docs`. - - -To build and serve docs, use the commands:: - - docker compose -f local.yml up docs - - - -Changes to files in `docs/_source` will be picked up and reloaded automatically. - -`Sphinx <https://www.sphinx-doc.org/>`_ is the tool used to build documentation. - -Docstrings to Documentation ----------------------------------------------------------------------- - -The sphinx extension `apidoc <https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html>`_ is used to automatically document code using signatures and docstrings. - -Numpy or Google style docstrings will be picked up from project files and available for documentation. See the `Napoleon <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/>`_ extension for details. - -For an in-use example, see the `page source <_sources/users.rst.txt>`_ for :ref:`users`. - -To compile all docstrings automatically into documentation source files, use the command: - :: - - make apidocs - - -This can be done in the docker container: - :: - - docker run --rm docs make apidocs diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index afb7889..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. pyblackbird-cc documentation master file, created by - sphinx-quickstart. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to pyblackbird-cc's documentation! -====================================================================== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - howto - pycharm/configuration - users - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 7e05187..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,46 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -c . -) -set SOURCEDIR=_source -set BUILDDIR=_build -set APP=..\alphabetlearning - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.Install sphinx-autobuild for live serving. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -b %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:livehtml -sphinx-autobuild -b html --open-browser -p 9000 --watch %APP% -c . %SOURCEDIR% %BUILDDIR%/html -GOTO :EOF - -:apidocs -sphinx-apidoc -o %SOURCEDIR%/api %APP% -GOTO :EOF - -:help -%SPHINXBUILD% -b help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/pycharm/configuration.rst b/docs/pycharm/configuration.rst deleted file mode 100644 index ffc7f61..0000000 --- a/docs/pycharm/configuration.rst +++ /dev/null @@ -1,70 +0,0 @@ -Docker Remote Debugging -======================= - -To connect to python remote interpreter inside docker, you have to make sure first, that Pycharm is aware of your docker. - -Go to *Settings > Build, Execution, Deployment > Docker*. If you are on linux, you can use docker directly using its socket `unix:///var/run/docker.sock`, if you are on Windows or Mac, make sure that you have docker-machine installed, then you can simply *Import credentials from Docker Machine*. - -.. image:: images/1.png - -Configure Remote Python Interpreter ------------------------------------ - -This repository comes with already prepared "Run/Debug Configurations" for docker. - -.. image:: images/2.png - -But as you can see, at the beginning there is something wrong with them. They have red X on django icon, and they cannot be used, without configuring remote python interpreter. To do that, you have to go to *Settings > Build, Execution, Deployment* first. - - -Next, you have to add new remote python interpreter, based on already tested deployment settings. Go to *Settings > Project > Project Interpreter*. Click on the cog icon, and click *Add Remote*. - -.. image:: images/3.png - -Switch to *Docker Compose* and select `local.yml` file from directory of your project, next set *Service name* to `django` - -.. image:: images/4.png - -Having that, click *OK*. Close *Settings* panel, and wait few seconds... - -.. image:: images/7.png - -After few seconds, all *Run/Debug Configurations* should be ready to use. - -.. image:: images/8.png - -**Things you can do with provided configuration**: - -* run and debug python code - -.. image:: images/f1.png - -* run and debug tests - -.. image:: images/f2.png -.. image:: images/f3.png - -* run and debug migrations or different django management commands - -.. image:: images/f4.png - -* and many others.. - -Known issues ------------- - -* Pycharm hangs on "Connecting to Debugger" - -.. image:: images/issue1.png - -This might be fault of your firewall. Take a look on this ticket - https://youtrack.jetbrains.com/issue/PY-18913 - -* Modified files in `.idea` directory - -Most of the files from `.idea/` were added to `.gitignore` with a few exceptions, which were made, to provide "ready to go" configuration. After adding remote interpreter some of these files are altered by PyCharm: - -.. image:: images/issue2.png - -In theory you can remove them from repository, but then, other people will lose a ability to initialize a project from provided configurations as you did. To get rid of this annoying state, you can run command:: - - $ git update-index --assume-unchanged alphabetlearning.iml diff --git a/docs/pycharm/images/1.png b/docs/pycharm/images/1.png Binary files differdeleted file mode 100644 index 06908a1..0000000 --- a/docs/pycharm/images/1.png +++ /dev/null diff --git a/docs/pycharm/images/2.png b/docs/pycharm/images/2.png Binary files differdeleted file mode 100644 index 1fb8cf1..0000000 --- a/docs/pycharm/images/2.png +++ /dev/null diff --git a/docs/pycharm/images/3.png b/docs/pycharm/images/3.png Binary files differdeleted file mode 100644 index 32c9335..0000000 --- a/docs/pycharm/images/3.png +++ /dev/null diff --git a/docs/pycharm/images/4.png b/docs/pycharm/images/4.png Binary files differdeleted file mode 100644 index cf07f9d..0000000 --- a/docs/pycharm/images/4.png +++ /dev/null diff --git a/docs/pycharm/images/7.png b/docs/pycharm/images/7.png Binary files differdeleted file mode 100644 index 4f8807e..0000000 --- a/docs/pycharm/images/7.png +++ /dev/null diff --git a/docs/pycharm/images/8.png b/docs/pycharm/images/8.png Binary files differdeleted file mode 100644 index 05946f2..0000000 --- a/docs/pycharm/images/8.png +++ /dev/null diff --git a/docs/pycharm/images/f1.png b/docs/pycharm/images/f1.png Binary files differdeleted file mode 100644 index 2d8c4b6..0000000 --- a/docs/pycharm/images/f1.png +++ /dev/null diff --git a/docs/pycharm/images/f2.png b/docs/pycharm/images/f2.png Binary files differdeleted file mode 100644 index b123a47..0000000 --- a/docs/pycharm/images/f2.png +++ /dev/null diff --git a/docs/pycharm/images/f3.png b/docs/pycharm/images/f3.png Binary files differdeleted file mode 100644 index 713ab54..0000000 --- a/docs/pycharm/images/f3.png +++ /dev/null diff --git a/docs/pycharm/images/f4.png b/docs/pycharm/images/f4.png Binary files differdeleted file mode 100644 index 11668ec..0000000 --- a/docs/pycharm/images/f4.png +++ /dev/null diff --git a/docs/pycharm/images/issue1.png b/docs/pycharm/images/issue1.png Binary files differdeleted file mode 100644 index 1bb68ee..0000000 --- a/docs/pycharm/images/issue1.png +++ /dev/null diff --git a/docs/pycharm/images/issue2.png b/docs/pycharm/images/issue2.png Binary files differdeleted file mode 100644 index 174f6fd..0000000 --- a/docs/pycharm/images/issue2.png +++ /dev/null diff --git a/docs/users.rst b/docs/users.rst deleted file mode 100644 index 0fac7bf..0000000 --- a/docs/users.rst +++ /dev/null @@ -1,15 +0,0 @@ - .. _users: - -Users -====================================================================== - -Starting a new project, it’s highly recommended to set up a custom user model, -even if the default User model is sufficient for you. - -This model behaves identically to the default user model, -but you’ll be able to customize it in the future if the need arises. - -.. automodule:: alphabetlearning.users.models - :members: - :noindex: - |