From f91474c05783bbc9bced21ff147f629ea17ab9b6 Mon Sep 17 00:00:00 2001 From: Nekmo Date: Wed, 20 May 2020 01:52:39 +0200 Subject: [PATCH] Issue #28: Create docs --- AUTHORS.rst | 13 +++++ CONTRIBUTING.rst | 114 ++++++++++++++++++++++++++++++++++++++++++ docs/Makefile | 1 - docs/authors.rst | 1 + docs/conf.py | 3 ++ docs/contributing.rst | 1 + docs/history.rst | 1 + docs/index.rst | 21 +++++++- docs/installation.rst | 39 +++++++++++++++ docs/readme.rst | 3 +- docs/usage.rst | 11 ++++ requirements-dev.txt | 3 ++ 12 files changed, 206 insertions(+), 5 deletions(-) create mode 100644 AUTHORS.rst create mode 100644 CONTRIBUTING.rst create mode 100644 docs/authors.rst create mode 100644 docs/contributing.rst create mode 100644 docs/history.rst create mode 100644 docs/installation.rst create mode 100644 docs/usage.rst create mode 100644 requirements-dev.txt diff --git a/AUTHORS.rst b/AUTHORS.rst new file mode 100644 index 0000000..de02d20 --- /dev/null +++ b/AUTHORS.rst @@ -0,0 +1,13 @@ +======= +Credits +======= + +Development Lead +---------------- + +* Nekmo + +Contributors +------------ + +None yet. Why not be the first? diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..8feefdf --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,114 @@ +.. highlight:: shell + +============ +Contributing +============ + +Contributions are welcome, and they are greatly appreciated! Every +little bit helps, and credit will always be given. + +You can contribute in many ways: + +Types of Contributions +---------------------- + +Report Bugs +~~~~~~~~~~~ + +Report bugs at https://github.com/Nekmo/telegram-upload/issues. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting. +* Detailed steps to reproduce the bug. + +Fix Bugs +~~~~~~~~ + +Look through the GitHub issues for bugs. Anything tagged with "bug" +and "help wanted" is open to whoever wants to implement it. + +Implement Features +~~~~~~~~~~~~~~~~~~ + +Look through the GitHub issues for features. Anything tagged with "enhancement" +and "help wanted" is open to whoever wants to implement it. + +Write Documentation +~~~~~~~~~~~~~~~~~~~ + +telegram-upload could always use more documentation, whether as part of the +official telegram-upload docs, in docstrings, or even on the web in blog posts, +articles, and such. + +Submit Feedback +~~~~~~~~~~~~~~~ + +The best way to send feedback is to file an issue at https://github.com/Nekmo/telegram-upload/issues. + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that contributions + are welcome :) + +Get Started! +------------ + +Ready to contribute? Here's how to set up `telegram-upload` for local development. + +1. Fork the `telegram-upload` repo on GitHub. +2. Clone your fork locally:: + + $ git clone git@github.com:your_name_here/telegram-upload.git + +3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:: + + $ mkvirtualenv telegram-upload + $ cd telegram-upload/ + $ python setup.py develop + +4. Create a branch for local development:: + + $ git checkout -b name-of-your-bugfix-or-feature + + Now you can make your changes locally. + +5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:: + + $ flake8 telegram_upload tests + $ python setup.py test or py.test + $ tox + + To get flake8 and tox, just pip install them into your virtualenv. + +6. Commit your changes and push your branch to GitHub:: + + $ git add . + $ git commit -m "Your detailed description of your changes." + $ git push origin name-of-your-bugfix-or-feature + +7. Submit a pull request through the GitHub website. + +Pull Request Guidelines +----------------------- + +Before you submit a pull request, check that it meets these guidelines: + +1. The pull request should include tests. +2. If the pull request adds functionality, the docs should be updated. Put + your new functionality into a function with a docstring, and add the + feature to the list in README.rst. +3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check + https://travis-ci.org/Nekmo/telegram-upload/pull_requests + and make sure that the tests pass for all supported Python versions. + +Tips +---- + +To run a subset of tests:: + + + $ python -m unittest tests.test_telegram_upload diff --git a/docs/Makefile b/docs/Makefile index 4e33e68..61673da 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -69,7 +69,6 @@ pdf: @echo "Build finished. The PDF file is in $(BUILDDIR)/." html: - $(SPHINXAPIDOC) -o . ../ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/docs/authors.rst b/docs/authors.rst new file mode 100644 index 0000000..e122f91 --- /dev/null +++ b/docs/authors.rst @@ -0,0 +1 @@ +.. include:: ../AUTHORS.rst diff --git a/docs/conf.py b/docs/conf.py index 6396c71..ad9dade 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,6 +28,8 @@ # version is used. directory = os.path.dirname(os.path.abspath(__file__)) +sys.path.append(os.path.abspath(os.path.join(directory, '../'))) + # sys.path.append(os.path.abspath(os.path.join(directory, '../'))) # os.environ['DJANGO_SETTINGS_MODULE'] = 'Google Keep CLI.settings.develop' # django.setup() @@ -42,6 +44,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', + 'sphinx_click.ext' # 'sphinxcontrib.autohttp.drf', # 'sphinxcontrib_django', ] diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..e582053 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst diff --git a/docs/history.rst b/docs/history.rst new file mode 100644 index 0000000..2506499 --- /dev/null +++ b/docs/history.rst @@ -0,0 +1 @@ +.. include:: ../HISTORY.rst diff --git a/docs/index.rst b/docs/index.rst index 376369c..4e6b0fc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,28 @@ -Google Keep CLI documentation -============================================= +Welcome to gkeep's documentation! +================================= +Google Keep Command Line Interface (CLI). Create and update notes from the command line. Use this program to automate +the creation of notes. + +To **install** gkeep, run this command in your terminal: + +.. code-block:: console + + $ pip install -U gkeep + + +Contents +-------- .. toctree:: :maxdepth: 2 :glob: + installation readme + usage + contributing + authors + history .. _ modules diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..f895928 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,39 @@ +.. highlight:: console + +============ +Installation +============ + + +Stable release +-------------- + +To install gkeep, run these commands in your terminal: + +.. code-block:: console + + $ sudo pip3 install -U gkeep + +This is the preferred method to install gkeep, as it will always install the most recent stable release. + +If you don't have `pip`_ installed, this `Python installation guide`_ can guide +you through the process. + +.. _pip: https://pip.pypa.io +.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/ + + +Other releases +-------------- +You can install other versions from Pypi using:: + + $ pip install gkeep== + +For versions that are not in Pypi (it is a development version):: + + $ pip install git+https://github.com/Nekmo/gkeep.git@#egg=gkeep + + +If you do not have git installed:: + + $ pip install https://github.com/Nekmo/gkeep/archive/.zip diff --git a/docs/readme.rst b/docs/readme.rst index 139597f..72a3355 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -1,2 +1 @@ - - +.. include:: ../README.rst diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..821802a --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,11 @@ + +Usage +##### + +.. click:: google_keep_tasks.management:notes + :prog: gkeep notes + :show-nested: + +.. click:: google_keep_tasks.management:items + :prog: gkeep items + :show-nested: diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..7f90d17 --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,3 @@ +-r requirements.txt +bumpversion +sphinx-click