docs: Create aims.md and move content to it

Author: MichaelCurrin

docs/README.md

@@ -4,42 +4,6 @@
 A project to explore the Github GraphQL API for fun and to output data on repos, users and commits for reporting.
 
 
-## Aims
-
-If you want to learn about GraphQL, GraphQL + Python integration, or to do reporting on Github data using the GraphQL API, then this project is for you. See the headings in this section.
-
-
-### GraphQL reference
-
-If you came here just to look at GraphQL queries that get data from Github, see the [queries](/ghgql/queries) directory. You can paste those in Github's [GraphQL Explorer](https://developer.github.com/v4/explorer/) and run them against public data. For some queries you need to add JSON params in the query variables section.
-
-If you want to download the results as text or CSV files or automate the requests for many pages of data, then follow the [documentation](#documentation) section below to setup the project then run the command-line Python scripts which generate the reports. The scripts use the GQL queries internally.
-
-Why _GraphQL_ and not the _REST_ API? This project arose because of speed and rate limit issues with using _REST_ API for large volumes of commit data for _Github_. But, the _GraphQL_ API is about **100 times faster**, in many cases such as getting a page of 100 commits rather than one commit from the REST API commit endpoint. See the Datasources doc's [GraphQL benefits](/datasources.md#graphql-benefits) section for more details.
-
-### GraphQL + Python reference
-
-Another aim of this project is to explore how to run _GraphQL_ queries with _Python_. This work here can be used as a reference for programmers new to this area. The understanding of querying Github can be applied to other _GraphQL_ APIs.
-
-No library specific to GraphQL or Github is used. Rather this project's scripts use Python [requests](https://requests.kennethreitz.org/en/master/) to send a query string and optional query parameters to the GraphQL API.
-
-The project includes Python scripts and _GraphQL_ queries of varying complexity. Some reports multiple pages of data. Some accept command-line arguments. One of them reads required report data from a config file.
-
-### Reporting
-
-The reporting goal of this project is to fetch stats about Github repos of interest and generate reports.
-
-The GraphQL API is used to get this data at scale, which enables quick reporting on a even large Github organization or user account with many repos. This project's reports generally fetch data in a single request that otherwise take 100 or more requests to the REST API. Additionally, some of the report script in this project have pagination built in, to get data beyond the first page.
-
-The response data is parsed and then printed on the screen or written to CSV reports.
-
-Here is an outline of the report scripts available in this project, with links to them in usage document.
-
-- [Demos reports](/usage.md#demo-reports) - A few simple scripts.
-- [Repo summary reports](/usage.md#repo-summary-reports) - Get metadata about reports or counts of commits.
-- [Commit reports](/usage.md#commit-reports) - Get the _git_ commit history across multiple repos and to see how your organization or team members contribute.
-
-
 ## Project requirements
 
 You need the following to run this project:
@@ -54,6 +18,7 @@ You need the following to run this project:
 
 See the following guides so you can use this project to generate some reports for yourself on users or repos you are interested in. Note that these only cover the case of a Unix-style environment.
 
+- [Aims](/aims.md) - The main purposes for this project and how they could benefit you.
 - [Installation](/installation.md) - Setup project environment and configs.
 - [Usage](/usage.md) - Run scripts to generate reports.
 - [Datasources](/datasources.md) - Info and links around APIs.

docs/aims.md

@@ -0,0 +1,30 @@
+# Aims
+
+If you want to learn about GraphQL, GraphQL + Python integration, or to do reporting on Github data using the GraphQL API, then this project is for you.
+
+
+## GraphQL reference
+
+If you came here just to look at GraphQL queries that get data from Github, see the [queries](/ghgql/queries) directory. You can paste those in Github's [GraphQL Explorer](https://developer.github.com/v4/explorer/) and run them against public data. For some queries you need to add JSON params in the query variables section.
+
+If you want to download the results as text or CSV files or automate the requests for many pages of data, then follow the [documentation](#documentation) section below to setup the project then run the command-line Python scripts which generate the reports. The scripts use the GQL queries internally.
+
+Why _GraphQL_ and not the _REST_ API? This project arose because of speed and rate limit issues with using _REST_ API for large volumes of commit data for _Github_. But, the _GraphQL_ API is about **100 times faster**, in many cases such as getting a page of 100 commits rather than one commit from the REST API commit endpoint. See the Datasources doc's [GraphQL benefits](/datasources.md#graphql-benefits) section for more details.
+
+## GraphQL + Python reference
+
+Another aim of this project is to explore how to run _GraphQL_ queries with _Python_. This work here can be used as a reference for programmers new to this area. The understanding of querying Github can be applied to other _GraphQL_ APIs.
+
+No library specific to GraphQL or Github is used. Rather this project's scripts use Python [requests](https://requests.kennethreitz.org/en/master/) to send a query string and optional query parameters to the GraphQL API.
+
+The project includes Python scripts and _GraphQL_ queries of varying complexity. Some reports multiple pages of data. Some accept command-line arguments. One of them reads required report data from a config file.
+
+## Reporting
+
+The reporting goal of this project is to fetch stats about Github repos of interest and then generate reports.
+
+The GraphQL API is used to get this data at scale, which enables quick reporting on a even large Github organization or user account with many repos. This project's reports generally fetch data in a single request that otherwise take 100 or more requests to the REST API. Additionally, some of the report script in this project have pagination built in, to get data beyond the first page.
+
+The response data is parsed and then printed on the screen or written to CSV reports.
+
+See the [usage](/usage.md) page for details on what reports you get.

docs/usage.md

@@ -2,6 +2,14 @@
 
 Follow in the instructions in this section to run the scripts in this project.
 
+**Table of contents**
+
+- [Activate environment](#activate-environment)
+- [Demos reports](#demo-reports) - A few simple scripts.
+- [Repo summary reports](#repo-summary-reports) - Get metadata about reports or counts of commits.
+- [Commit reports](#commit-reports) - Get the _git_ commit history across multiple repos and to see how your organization or team members contribute.
+
+
 ## Activate environment
 
 Activate the virtual environment and navigate to the app directory.
@@ -15,7 +23,7 @@ $ cd ghgql
 Note: If you use the _VS Code_ IDE and open a terminal _after_ the Python Extension has loaded, this will be done for you because of the configs that come with this project.
 
 
-## Demos reports
+## Demo reports
 
 Run the simple demo scripts, which take no inputs or configs (other than access token). They showcase querying the GraphQL and printing the JSON responses to the screen.
 
@@ -149,7 +157,7 @@ To change the report output, update and save the config then rerun the report.
 
 ### Experimental scripts
 
-Run the [query.py](/ghgql/query.py) script along with the path of target queries form the [queries](/ghgql/queries) directory.
+Run the `ghgql/query.py` script along with the path of target queries form the `ghgql/queries` directory.
 
 You can view the query text first, to see what variables are needed. As you will get an API error printed to the console if you omit a required variable.