From 5655f194b311c50126713e6f40440e7f89be6479 Mon Sep 17 00:00:00 2001 From: jasdeepgill <51393196+jasdeepgill@users.noreply.github.com> Date: Sat, 21 Dec 2019 02:33:02 -0800 Subject: [PATCH] Various text improvements to documentation. * Minor text improvements to faq.rst * Fixed minor mistake to faq.rst * Minor grammar fixes to troubleshooting.rst * Minor grammar improvements to quickstart.rst * Minor text changes to install.rst * Improved text in multiple-sites.rst * Misspelled word * Minor text changes --- docs/docs/extras/deployment.rst | 4 ++-- docs/docs/install.rst | 6 +++--- docs/docs/man/index.rst | 2 +- docs/docs/quickstart.rst | 9 +++++---- docs/docs/setup/multiple-sites.rst | 4 ++-- docs/docs/troubleshooting.rst | 6 +++--- docs/faq.rst | 10 +++++----- 7 files changed, 21 insertions(+), 20 deletions(-) diff --git a/docs/docs/extras/deployment.rst b/docs/docs/extras/deployment.rst index 6f27095..eba21b9 100644 --- a/docs/docs/extras/deployment.rst +++ b/docs/docs/extras/deployment.rst @@ -4,7 +4,7 @@ Deployment Isso ships with a built-in web server, which is useful for the initial setup and may be used in production for low-traffic sites (up to 20 requests per second). Running a "real" WSGI server supports nice things such as UNIX domain -sockets, daemonization and solid HTTP handler while being more stable, secure +sockets, daemonization and solid HTTP handler. WSGI servers are more stable, secure and web-scale than the built-in web server. * gevent_, coroutine-based network library @@ -188,7 +188,7 @@ The Apache configuration will then be similar to the following: You will need to adjust the user and group according to your Apache installation and -security policy. Be also aware that the directory containing the comments database must +security policy. Be aware that the directory containing the comments database must be writable by the user or group running the WSGI daemon process: having a writable database only is not enough, since SQLite will need to create a lock file in the same directory. diff --git a/docs/docs/install.rst b/docs/docs/install.rst index f82ec6a..07eec9a 100644 --- a/docs/docs/install.rst +++ b/docs/docs/install.rst @@ -22,12 +22,12 @@ libraries, but most likely not all required by Isso (or in an up-to-date version – looking at you, Debian!). That's why most Python developers use the `Python Package Index`_ to get their -dependencies. But the most important rule: never install *anything* from PyPi +dependencies. The most important rule to follow is to never install *anything* from PyPi as root. Not because of malicious software, but because you *will* break your system. ``easy_install`` is one tool to mess up your system. Another package manager is ``pip``. If you ever searched for an issue with Python/pip and Stackoverflow is -suggesting your ``easy_install pip`` or ``pip install --upgrade pip`` (as root +suggesting you ``easy_install pip`` or ``pip install --upgrade pip`` (as root of course!), you are doing it wrong. `Why you should not use Python's easy_install carelessly on Debian`_ is worth the read. @@ -228,7 +228,7 @@ don't use FastCGi or uWSGI: If you're writing your own init script, you can utilize ``start-stop-daemon`` to run Isso in the background (Isso runs in the foreground usually). Below you -find a very basic SysVinit script which you can use for inspiration: +will find a very basic SysVinit script which you can use for inspiration: .. code-block:: sh diff --git a/docs/docs/man/index.rst b/docs/docs/man/index.rst index 072b4c4..e9ad747 100644 --- a/docs/docs/man/index.rst +++ b/docs/docs/man/index.rst @@ -6,7 +6,7 @@ What's Isso? Isso is a lightweight commenting server similar to Disqus. It allows anonymous comments, maintains identity and is simple to administrate. It uses JavaScript -and cross-origin ressource sharing for easy integration into static websites. +and cross-origin resource sharing for easy integration into static websites. No, I meant "Isso" ------------------ diff --git a/docs/docs/quickstart.rst b/docs/docs/quickstart.rst index c420f03..3b45f03 100644 --- a/docs/docs/quickstart.rst +++ b/docs/docs/quickstart.rst @@ -2,7 +2,7 @@ Quickstart ========== Assuming you have successfully :doc:`installed ` Isso, here's -a quickstart quide that covers the most common setup. Sections covered: +a quickstart guide that covers the most common setup. Sections covered: .. contents:: :local: @@ -18,7 +18,8 @@ sane defaults. .. code-block:: ini [general] - ; database location, check permissions, automatically created if not exists + ; database location, check permissions, automatically created if it + does not exist dbpath = /var/lib/isso/comments.db ; your website or blog (not the location of Isso!) host = http://example.tld/ @@ -62,7 +63,7 @@ Migration Isso provides a tool for importing comments from Disqus_ or WordPress_. You can also import comments from any other comment system, but this topic is more -complex and covered in :doc:`advanced migration `. +complex and is covered in :doc:`advanced migration `. To export your comments from Disqus, log into Disqus, go to your website, click on *Discussions* and select the *Export* tab. You'll receive an email with your @@ -140,7 +141,7 @@ a comment to see if the setup works. If not, see :doc:`troubleshooting`. Going Further ------------- -There are several server and client configuration options uncovered in this +There are several server and client configuration options not covered in this quickstart, check out :doc:`configuration/server` and :doc:`configuration/client` for more information. For further website integration, see :doc:`extras/advanced-integration`. diff --git a/docs/docs/setup/multiple-sites.rst b/docs/docs/setup/multiple-sites.rst index bc39bac..3e2a2df 100644 --- a/docs/docs/setup/multiple-sites.rst +++ b/docs/docs/setup/multiple-sites.rst @@ -5,8 +5,8 @@ Multiple Sites -------------- Isso is designed to serve comments for a single website and therefore stores -comments for a relative URL to support HTTP, HTTPS and even domain transfers -without manual intervention. But you can chain Isso to support multiple +comments for a relative URL. This is done to support HTTP, HTTPS and even domain transfers +without manual intervention. You can chain Isso to support multiple websites on different domains. The following example uses `gunicorn `_ as WSGI server ( diff --git a/docs/docs/troubleshooting.rst b/docs/docs/troubleshooting.rst index a395a0a..ebb5248 100644 --- a/docs/docs/troubleshooting.rst +++ b/docs/docs/troubleshooting.rst @@ -4,7 +4,7 @@ Troubleshooting For uberspace users ------------------- Some uberspace users experienced problems with isso and they solved their -issue by adding `DirectoryIndex disabled` as the first line in the `.htaccess` +issues by adding `DirectoryIndex disabled` as the first line in the `.htaccess` file for the domain the isso server is running on. pkg_ressources.DistributionNotFound @@ -29,9 +29,9 @@ encoding either in :envvar:`LANG`, :envvar:`LANGUAGE`, :envvar:`LC_ALL` or $ env LANG=C.UTF-8 isso [-h] [--version] ... -If none of the mentioned variables is set, the interaction with Isso will +If none of the mentioned variables are set, the interaction with Isso will likely fail (unable to print non-ascii characters to stdout/err, unable to -parse configuration file with non-ascii characters and to forth). +parse configuration file with non-ascii characters and so forth). The web console shows 404 Not Found responses --------------------------------------------- diff --git a/docs/faq.rst b/docs/faq.rst index 7848023..ad92a14 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -4,14 +4,14 @@ Frequently asked question Why SQLite3? ------------ -Although partially answered on the index page, here a more complete answer: If +Although partially answered on the index page, here is a more complete answer: If you manage massive amounts of comments, Isso is a really bad choice. Isso is -designed to be simple and easy to setup, not optimizied for high-traffic +designed to be simple and easy to setup, it is not optimized for high-traffic websites (use a `dedicated Disqus`_ instance then). - comments are not big data + Comments are not big data. -For example, 209 threads and 778 comments in total only need 620K (kilobyte) -memory. Excellent use case for SQLite. +For example, if you have 209 threads and 778 comments in total this only needs 620 kilobytes +of memory. This is an excellent use case for SQLite. .. _dedicated Disqus: