moved root folder documentation to /docs folder to reduce duplication

AUTHORS.rst

@@ -1,15 +0,0 @@
-=======
-Credits
-=======
-
-Development Lead
-----------------
-
-* Nidhal Baccouri <[email protected]>
-
-Contributors
-------------
-
-@prataffel
-@senk8
-@nothead31

CONTRIBUTING.rst

@@ -1,128 +0,0 @@
-.. 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/nidhaloff/deep_translator/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
-~~~~~~~~~~~~~~~~~~~
-
-deep_translator could always use more documentation, whether as part of the
-official deep_translator 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/nidhaloff/deep_translator/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 `deep_translator` for local development.
-
-1. Fork the `deep_translator` repo on GitHub.
-2. Clone your fork locally::
-
-    $ git clone [email protected]:your_name_here/deep_translator.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 deep_translator
-    $ cd deep_translator/
-    $ 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 deep_translator tests
-    $ python setup.py test or pytest
-    $ 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 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check
-   https://travis-ci.com/nidhaloff/deep_translator/pull_requests
-   and make sure that the tests pass for all supported Python versions.
-
-Tips
-----
-
-To run a subset of tests::
-
-$ pytest -ra
-
-
-Deploying
----------
-
-A reminder for the maintainers on how to deploy.
-Make sure all your changes are committed (including an entry in HISTORY.rst).
-Then run::
-
-$ bump2version patch # possible: major / minor / patch
-$ git push
-$ git push --tags
-
-Travis will then deploy to PyPI if tests pass.

HISTORY.rst

@@ -1,19 +0,0 @@
-==================
-Important History
-==================
-
-- 1.4.4 added support for papago, added opt params, fixed deepl free api
-- 1.4.3 added support deepl free api
-- 1.4.2 added proxy support
-- 1.3.4 bug fixes for the dutch language
-- 1.3.3 fixed bug in google translate
-
-- 1.2.5: added support for the DeepL translator
-- 1.2.4: added support for the QCRI translator
-- 1.2.1: added support for the yandex translator
-- 1.1.9: fixed bug in requests
-- 1.1.5: added language detection
-- 1.1.3: added support for mymemory
-- 1.0.4: added support for pons
-- 1.0.2: added support for linguee
-- 1.0.0: added support for google translate

README.rst → docs/README.rst

@@ -2,7 +2,7 @@
 deep-translator
 ##################
 
-.. image:: assets/icon.jpg
+.. image:: ../assets/icon.jpg
     :width: 100
     :align: center
     :alt: deep-translator-icon
@@ -125,7 +125,7 @@ Install the stable release:
 
 .. code-block:: console
 
-    $ pip install -U deep_translator
+    $ pip install -U deep-translator
 
 take a look at the docs if you want to install from source.
 
@@ -135,14 +135,14 @@ Quick Start
 
 .. code-block:: python
 
-    from deep_translator import GoogleTranslator
+    from deep-translator import GoogleTranslator
     translated = GoogleTranslator(source='auto', target='de').translate("keep it up, you are awesome")  # output -> Weiter so, du bist großartig
 
 or using proxies:
 
 .. code-block:: python
 
-    from deep_translator import GoogleTranslator
+    from deep-translator import GoogleTranslator
 
     proxies_example = {
         "https": "34.195.196.27:8080",
@@ -155,7 +155,7 @@ or even directly from terminal:
 
 .. code-block:: console
 
-    $ deep_translator -trans "google" -src "en" -tg "de" -txt "keep it up, you are awesome"
+    $ deep-translator -trans "google" -src "en" -tg "de" -txt "keep it up, you are awesome"
 
 
 =====
@@ -175,7 +175,7 @@ Imports
 
 .. code-block:: python
 
-    from deep_translator import (GoogleTranslator,
+    from deep-translator import (GoogleTranslator,
                                  MicrosoftTranslator,
                                  PonsTranslator,
                                  LingueeTranslator,
@@ -536,7 +536,7 @@ can be used with all supported translators.
 
 .. code-block:: python
 
-    from deep_translator import GoogleTranslator
+    from deep-translator import GoogleTranslator
 
     # define your proxy configs:
     proxies_example = {
@@ -551,71 +551,42 @@ can be used with all supported translators.
 Usage from Terminal
 --------------------
 
-For a quick access, you can use the deep_translator from terminal. For this to work, you need to provide
-the right arguments, which are the translator you want to use, source language, target language and the text
-you want to translate.
+Deep-translator supports a series of command line arguments for quick and simple access to the translators directly in your console.
 
-For example, provide "google" as an argument to use the google translator. Alternatively you can use
-the other supported translators. Just read the documentation to have an overview about the supported translators in this library.
-
-.. code-block:: console
+.. note::
 
-    $ deep_translator --translator "google" --source "english" --target "german" --text "happy coding"
+    The program accepts ``deep-translator`` or ``dt`` as a command, feel free to substitute whichever you prefer.
 
-Or you can go for the short version:
+For a list of available translators:
 
 .. code-block:: console
 
-    $ deep_translator -trans "google" -src "english" -tg "german" -txt "happy coding"
+    $ deep-translator list
 
-If you want, you can also pass the source and target language by their abbreviation
+To translate a string or line of text:
 
 .. code-block:: console
 
-    $ deep_translator -trans "google" -src "en" -tg "de" -txt "happy coding"
+    $ deep-translator google --source "english" --target "german" --text "happy coding"
 
-If you want the list of languages supported by a translator service, just pass the translator service as an argument to the -trans flag followed by the -lang/--languages flag. For example:
+Alternate short option names, along with using language abbreviations:
 
 .. code-block:: console
 
-    $ deep_translator -trans "google" -lang
+    $ deep-translator google -src "en" -tgt "de" -txt "happy coding"
 
-======
-Tests
-======
 
-- Install dev requirements
+Finally, to retrieve a list of available languages for a given translator:
 
 .. code-block:: console
 
-    $ pip install -r requirements_dev.txt
-
-- Or just install pytest
-
-.. code-block:: console
-
-    $ pip install pytest
-
-
-- you can run tests individually for each translator by passing the prefix **test_** followed by the translator name as an argument to pytest.
-
-.. code-block:: console
-
-    $ pytest test_google_trans
-    $ pytest test_linguee
-    $ pytest test_mymemory
-    $ pytest test_pons
-
-- Alternatively, you can run the test suite
-
-.. code-block:: console
-
-    $ pytest -ra
-
-
-
+    $ deep-translator languages google
 
+======
+Tests
+======
 
+Developers can install the development version of deep-translator and execute unit tests to verify functionality. For more information on doing this, see `the contribution guidelines <https://deep-translator.readthedocs.io/en/latest/contributing.html/>`_
 
 ========
 Links
@@ -668,12 +639,12 @@ Copyright (c) 2020-present, Nidhal Baccouri
 The Translator++ mobile app
 ===========================
 
-.. image:: assets/app-icon.png
+.. image:: ../assets/app-icon.png
     :width: 100
     :alt: Icon of the app
 
 
-After developing the deep_translator, I realized how cool this would be if I can use it as an app on my mobile phone.
+After developing the deep-translator, I realized how cool this would be if I can use it as an app on my mobile phone.
 Sure, there is google translate, pons and linguee apps etc.. but isn't it cooler to make an app where all these
 translators are integrated?
 
@@ -683,8 +654,8 @@ I open sourced the `Translator++ app <https://github.com/nidhaloff/deep-translat
 Feel free to take a look at the code or make a pull request ;)
 
 .. note::
-    The Translator++ app is based on the deep_translator package. I just built the app to prove the capabilities
-    of the deep_translator package ;)
+    The Translator++ app is based on the deep-translator package. I just built the app to prove the capabilities
+    of the deep-translator package ;)
 
 I published the first release on google play store on 02-08-2020
 
@@ -692,22 +663,22 @@ Here are some screenshots:
 
 - Phone
 
-.. image:: assets/translator1.jpg
+.. image:: ../assets/translator1.jpg
     :width: 30%
     :height: 200
     :alt: screenshot1
-.. image:: assets/translator2.jpg
+.. image:: ../assets/translator2.jpg
     :width: 30%
     :height: 200
     :alt: screenshot2
-.. image:: assets/spinner.jpg
+.. image:: ../assets/spinner.jpg
     :width: 30%
     :height: 200
     :alt: spinner
 
 - Tablet:
 
-.. image:: assets/hz_view.png
+.. image:: ../assets/hz_view.png
     :width: 100%
     :height: 300
     :alt: screenshot3

docs/authors.rst

@@ -1 +1,15 @@
-.. include:: ../AUTHORS.rst
+=======
+Credits
+=======
+
+Development Lead
+----------------
+
+* Nidhal Baccouri <[email protected]>
+
+Contributors
+------------
+
+@prataffel
+@senk8
+@nothead31

docs/contributing.rst

@@ -1 +1,131 @@
-.. include:: ../CONTRIBUTING.rst
+.. 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/nidhaloff/deep_translator/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.
+* If the bug includes a tracelog, include that in your bug report. Remember on github, you can enclose code or console output in ``` insert code here ```.
+
+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.
+
+.. note::
+
+    You can contact @nothead31 or comment on the issue if you wish to be listed under 'Assigned'.
+
+Write Documentation
+~~~~~~~~~~~~~~~~~~~
+
+deep_translator could always use more documentation, whether as part of the official deep_translator docs, in docstrings, or even on the web in blog posts, articles, and such. If you do a write-up on your own site, please let us know and we will add a link to it in the official documentation!
+
+Submit Feedback
+~~~~~~~~~~~~~~~
+
+The best way to send feedback is to file an issue at https://github.com/nidhaloff/deep_translator/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 `deep_translator` for local development.
+
+1. Fork the `deep_translator` repo on GitHub.
+2. Clone your fork locally::
+
+    $ git clone [email protected]:your_name_here/deep_translator.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::
+
+    $ cd path/to/project
+    $ poetry shell
+    $ poetry install
+
+ .. note::
+
+    ``poetry install`` will automatically install all package dependencies AND development dependencies. If you only want to run the package, append --no-dev to the command.
+
+4. Create a branch for local development::
+
+    $ git checkout -b name-of-your-bugfix-or-feature
+
+   Now you can make your changes locally.
+
+5. Ensure your changes are covered by test modules and that the tests pass with pytest before committing.
+
+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 any relevant tests (located under :file:`.deep_translator/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. Pull requests are automatically tested on GitHub for compatability with Python version 3.7, 3.8, and 3.9. Please review your test results and ensure your request passes all tests.
+
+Tips
+----
+
+To run only certain tests::
+
+   $ pytest -ra
+
+.. note::
+
+   will run all tests, excluding any that previously passed, and provides a simple test report.
+
+    $ pytest test_mod.py
+
+.. note::
+
+   Runs only the tests in the named testing module. Useful for only testing a subset of functionality.
+
+Deploying
+---------
+
+A reminder for the maintainers on how to deploy.
+Make sure all your changes are committed (including an entry in HISTORY.rst).
+Then run::
+
+   $ poetry version major|minor|patch
+   $ git push
+   $ git push --tags
+
+After pushing a new version to the master branch, github will build a package and upload it to PyPI.

docs/history.rst

@@ -1 +1,20 @@
-.. include:: ../HISTORY.rst
+==================
+Important History
+==================
+
+- 1.5.0 improved cli functionality with streamlined commands and numerous bugfixes.
+- 1.4.4 added support for papago, added opt params, fixed deepl free api
+- 1.4.3 added support deepl free api
+- 1.4.2 added proxy support
+- 1.3.4 bug fixes for the dutch language
+- 1.3.3 fixed bug in google translate
+
+- 1.2.5: added support for the DeepL translator
+- 1.2.4: added support for the QCRI translator
+- 1.2.1: added support for the yandex translator
+- 1.1.9: fixed bug in requests
+- 1.1.5: added language detection
+- 1.1.3: added support for mymemory
+- 1.0.4: added support for pons
+- 1.0.2: added support for linguee
+- 1.0.0: added support for google translate

docs/readme.rst

@@ -1 +0,0 @@
-.. include:: ../README.rst