#109 Update documentation

roskakori · Jun 25, 2023 · efc6b31 · efc6b31
1 parent c441643
commit efc6b31
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 27 deletions.
diff --git a/README.md b/README.md
@@ -39,7 +39,7 @@ $ pygount ~/projects/example
 To limit the analysis to certain file types identified by their suffix:
 
 ```bash
-$ pygount --suffix=cfg,py,yml  ~/projects/example
+$ pygount --suffix=cfg,py,yml ~/projects/example
 ```
 
 To get a summary of each programming language with sum counts and percentage:
@@ -48,22 +48,35 @@ To get a summary of each programming language with sum counts and percentage:
 $ pygount --format=summary ~/projects/example
 ```
 
-As an example here is the summary output for pygount's own source code:
+To analyze a remote git repository directly without having to clone it first:
+
+```bash
+$ pygount --format=summary https://github.com/roskakori/pygount.git
+```
+
+You can pass a specific revision at the end of the remote URL:
+
+```bash
+$ pygount --format=summary https://github.com/roskakori/pygount.git/v1.5.1
+```
+
+This example results in the following summary output:
 
 ```
-    Language      Files    %     Code    %     Comment    %
-----------------  -----  ------  ----  ------  -------  ------
-Python               19   51.35  1924   72.99      322   86.10
-reStructuredText      7   18.92   332   12.59        7    1.87
-markdown              3    8.11   327   12.41        1    0.27
-Batchfile             1    2.70    24    0.91        1    0.27
-YAML                  1    2.70    11    0.42        2    0.53
-Makefile              1    2.70     9    0.34        7    1.87
-INI                   1    2.70     5    0.19        0    0.00
-TOML                  1    2.70     4    0.15        0    0.00
-Text                  3    8.11     0    0.00       34    9.09
-----------------  -----  ------  ----  ------  -------  ------
-Sum total            37          2636              374
+┏━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━━━━┳━━━━━━┓
+┃ Language         ┃ Files ┃     % ┃ Code ┃    % ┃ Comment ┃    % ┃
+┡━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━┩
+│ Python           │    18 │  47.4 │ 2132 │ 63.6 │     418 │ 12.5 │
+│ TOML             │     2 │   5.3 │ 1204 │ 82.7 │       1 │  0.1 │
+│ reStructuredText │     9 │  23.7 │  566 │ 64.8 │       1 │  0.1 │
+│ Markdown         │     3 │   7.9 │   53 │ 49.1 │       0 │  0.0 │
+│ Batchfile        │     1 │   2.6 │   24 │ 68.6 │       1 │  2.9 │
+│ Text only        │     2 │   5.3 │   24 │ 82.8 │       0 │  0.0 │
+│ Bash             │     2 │   5.3 │   12 │ 80.0 │       3 │ 20.0 │
+│ Makefile         │     1 │   2.6 │    9 │ 45.0 │       7 │ 35.0 │
+├──────────────────┼───────┼───────┼──────┼──────┼─────────┼──────┤
+│ Sum              │    38 │ 100.0 │ 4024 │ 68.4 │     431 │  7.3 │
+└──────────────────┴───────┴───────┴──────┴──────┴─────────┴──────┘
 ```
 
 Plenty of tools can post process SLOC information, for example the

diff --git a/docs/changes.rst b/docs/changes.rst
@@ -5,8 +5,11 @@ Changes
 
 This chapter describes the changes coming with each new version of pygount.
 
-Version 1.6.0, 2023-06-xx
+Version 1.6.0, 2023-06-26
 
+* Add support for analysis of remote git URL's in addition to local files
+  (contributed by Rojdi Thomallari, issue
+  `#109 <https://github.com/roskakori/pygount/issues/109>`_).
 * Removed support for Python 3.7.
 * Improved API:
 

diff --git a/docs/usage.rst b/docs/usage.rst
@@ -6,7 +6,7 @@ General
 
 .. program:: pygount
 
-Simply run and specify the folder to analyze recursively, for example:
+Run and specify the folder to analyze recursively, for example:
 
 .. code-block:: bash
 
@@ -75,27 +75,44 @@ easiest to deal with. For more information see :doc:`json`.
 
 
 Remote repositories
--------
+-------------------
 
-Pygount can analyze remote git repositories by shallow cloning to a temporary
-directory:
+Additionally to local files, pygount can analyze remote git repositories:
 
 .. code-block:: bash
 
     $ pygount https://github.com/roskakori/pygount.git
 
-* It supports mixing multiple URLs with or without local folders, for example:
+In the background, this creates a shallow clone of the repository in a
+temporary folder that after the analysis is is removed automatically.
+
+Therefore you need to have at read access to the repository.
+
+If you want to analyze a specific revision, specify it at the end of the URL:
+
+.. code-block:: bash
+
+    $ pygount https://github.com/roskakori/pygount.git/v1.6.0
+
+The remote URL supports the git standard protocols: git, HTTP/S and SSH.
 
 .. code-block:: bash
 
-    $ pygount https://github.com/roskakori/pygount.git ~/development/sometool
+    $ pygount git@github.com:username/project.git
+
+You can specify multiple repositories, for example to include both the
+web application, command line client and docker container of the
+`Weblate <https://weblate.org/>`_ project:
+
+.. code-block:: bash
 
-* It supports different protocols such as Git, HTTP/S and SSH.
-* The branch or tag can be specified in the URL, for example:
+    $  pygount https://github.com/WeblateOrg/weblate.git https://github.com/WeblateOrg/wlc.git  https://github.com/WeblateOrg/docker.git
+
+And you can even mix local files and remote repositories:
+
+.. code-block:: bash
 
-    * ``https://github.com/roskakori/pygount.git/master``
-    * ``https://github.com/roskakori/pygount.git/feature/branch``
-    * ``git@github.com:roskakori/pygount.git/v1.6.0``
+    $ pygount ~/projects/some https://github.com/roskakori/pygount.git
 
 
 Patterns