Readthedocs improvements, debugging, fixes #1841

.readthedocs.yml

@@ -0,0 +1,4 @@
+version: 2
+formats: all
+mkdocs:
+  configuration: mkdocs.yml

docs/developers/building-contributing.md

@@ -1,8 +1,8 @@
-<h1>Building, Testing, and Contributing</h1>
+# Building, Testing, and Contributing
 
 ## Building
 
-In the past, ddev would be checked out in the $GOPATH, but as of go 1.11, this is no longer appropriate. You should check out your fork *outside* the $GOPATH. 
+If you have `make` and docker, you can build for your environment with just `make`. Since the Makefile uses docker to build, it's not generally essential to install go on your machine, although it will make things easier. 
 
 Build/test/check static analysis with:
 

docs/index.md

@@ -1,4 +1,4 @@
-<h1>ddev Documentation</h1>
+## What is DDEV Local?
 
 [ddev](https://github.com/drud/ddev) is an open source tool that makes it dead simple to get local PHP development environments up and running within minutes. It's powerful and flexible as a result of its per-project environment configurations, which can be extended, version controlled, and shared. In short, ddev aims to allow development teams to use Docker in their workflow without the complexities of bespoke configuration.
 
@@ -10,21 +10,21 @@
 - docker-compose 1.21.0 and higher (bundled with Docker in Docker Desktop for Mac and Docker Desktop for Windows)
 - OS Support
   - macOS Sierra and higher (macOS 10.12 and higher; it should run anywhere Docker Desktop for Mac runs.
-  - Linux: Most Linux distributions which can run Docker-ce are fine. This includes at least Ubuntu 14.04+, Debian Jessie+, Fedora 25+. Make sure to follow the docker-ce [post-install steps](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user)
+  - Linux: Most Linux distributions which can run Docker-ce are fine. This includes at least Ubuntu 16.04+, Debian Jessie+, Fedora 25+. Make sure to follow the docker-ce [post-install steps](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user)
   - Windows 10 Pro or Enterprise with [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/)
   - Windows 10 Home (or other Windows version) with [Docker Toolbox](https://docs.docker.com/toolbox/toolbox_install_windows/)
 
 
-### Using ddev with other development environments
-ddev by default uses ports 80 and 443 on your system when projects are running. If you are using another local development environment you can either stop the other environment or configure ddev to use different ports. See [troubleshooting](https://ddev.readthedocs.io/en/stable/users/troubleshooting/#webserver-ports-are-already-occupied-by-another-webserver) for more detailed problemsolving.
+### Using ddev alongside other development environments
+ddev by default uses ports 80 and 443 on your system when projects are running. If you are using another local development environment you can either stop the other environment or configure ddev to use different ports. See [troubleshooting](users/troubleshooting.md#unable-listen) for more detailed problemsolving.
 
 ## Installation
 
 _When upgrading, please check the [release notes](https://github.com/drud/ddev/releases) for actions you might need to take on each project._
 
 ### Docker Installation
 
-Docker and docker-compose are required before anything will work with ddev. This is pretty easy on most environments, but we have a [docker_installation](users/docker_installation.md) page to help sort out the nuances, especially on Windows and Linux.
+Docker and docker-compose are required before anything will work with ddev. This is pretty easy on most environments, but see the [docker_installation](users/docker_installation.md) page to help sort out the details, especially on Windows and Linux.
 
 ### Homebrew/Linuxbrew - macOS/Linux
 

docs/users/cli-usage.md

@@ -1,4 +1,3 @@
-<h1>Using the ddev command line interface (CLI)</h1>
 
 Type `ddev` or `ddev -h`in a terminal window to see the available ddev commands. There are commands to configure a project, start, stop, describe, etc. Each command also has help. For example, `ddev stop -h` shows that `ddev rm` is an alias, and shows all the many flags that can be used with `ddev stop`.
 

docs/users/developer-tools.md

@@ -1,17 +1,20 @@
 <h1>Using Developer Tools with ddev</h1>
 
 ## Developer Tools Included in the Container
-We have included several useful developer tools in our containers. Run `ddev describe` to see the project information and services available for your project and how to access them.   
+Several useful developer tools are included inside the containers. Run `ddev describe` to see the project information and services available for your project and how to access them.   
 
-### Command-line Tools
-- MySQL Client (mysql) - Command-line interface for interacting with MySQL.
+### Command-line Tools in the Containers
+- MySQL Client (mysql) - Command-line interface for interacting with MySQL/MariaDB.
 - [Drush](http://www.drush.org) - Command-line shell and Unix scripting interface for Drupal.
 - [WP-CLI](http://wp-cli.org/) - Command-line tools for managing WordPress installations.
+- npm and yarn
+- node
+- sqlite3
 
 These tools can be accessed for single commands using [`ddev exec <command>`](cli-usage.md#executing-commands-in-containers) or [`ddev ssh`](cli-usage.md#ssh-into-containers) for an interactive bash or sh session.
 
 ### DDEV and Composer 
-We have included a built-in command to simplify use of [Composer](https://getcomposer.org/), the dependency manager for PHP, that allows a user to create and manage projects without having Composer installed on the host machine. Generally, executing any Composer command through DDEV is as simple as prepending the command with `ddev`. DDEV will execute the command at the project root in the web container, passing all arguments and flags to Composer. To execute Composer in other directories within the container, use `ddev ssh` or `ddev exec -d <dir>`. For example:
+ddev provides a built-in command to simplify use of [Composer](https://getcomposer.org/), the dependency manager for PHP, that allows a user to create and manage projects without having Composer installed on the host machine. Generally, executing any Composer command through DDEV is as simple as prepending the command with `ddev`. DDEV will execute the command at the project root in the web container, passing all arguments and flags to Composer. To execute Composer in other directories within the container, use `ddev ssh` or `ddev exec -d <dir>`. For example:
 
 `ddev composer help`
 `ddev composer require <package>`
@@ -85,5 +88,5 @@ The port referenced is unique per running project, and randomly chosen from avai
 
 **Note:** The host database port is likely to change any time a project is stopped/removed and then later started again.
 
-### Using Drush Installation on Host Machine
+### Using Drush 8 installed Installation on the Host Computer
 If you have PHP and Drush installed on your host system, you can use it to interact with a ddev project. On the host system the extra include ddev_drush_settings.php is written on startup and will allow drush to access the database server. This may not work for all drush commands because of course the actual webserver environment is not available.

docs/users/extend/config_yaml.md

@@ -26,7 +26,7 @@ the .ddev/config.yaml is the primary configuration for the project.
 | upload_dir | Relative path to upload directory used by `ddev import-files` | |
 | working_dir | explicitly specify the working directory used by `ddev exec` and `ddev ssh` | `working_dir: { web:  "/var/www", db: "/etc" }` would set the working directories for the web and db containers. |
 | omit_containers | Allows the project to not load specified containers | For example, `omit_containers: ["db", dba", "ddev-ssh-agent"]`. Currently only these containers are supported. Some containers can also be omitted globally in the ~/.ddev/global_config.yaml. Note that if you omit the "db" container, several standard features of ddev that access the database container will be unusuable. |
-| nfs_mount_enabled | Allows using NFS to mount the project into the container for performance reasons | See [nfsmount_enabled documentation](../../performance.md). This requires configuration on the host before it can be used. |
+| nfs_mount_enabled | Allows using NFS to mount the project into the container for performance reasons | See [nfsmount_enabled documentation](../performance.md). This requires configuration on the host before it can be used. |
 | host_https_port | Specify a specific and persistent https port for direct binding to the localhost interface | This is not commonly used, but a specific port can be provided here and the https URL will always remain the same. For example, if you put "59001", the project will always use "https://127.0.0.1:59001". for the localhost URL. (Note that the named URL is more commonly used and for most purposes is better.) If this is not set the port will change from `ddev start` to `ddev start` |
 | host_webserver_port | Specify a specific and persistent http port for direct binding to the localhost interface | This is not commonly used, but a specific port can be provided here and the https URL will always remain the same. For example, if you put "59000", the project will always use "http://127.0.0.1:59000". for the localhost URL. (Note that the named URL is more commonly used and for most purposes is better.) If this is not set the port will change from `ddev start` to `ddev start` |
 | host_db_port | localhost binding port for database server | If specified here, the database port will remain consistent. This is useful for configuration of host-side database browsers. Note, though, that `ddev sequelpro` and `ddev mysql` do all this automatically, as does the sample command `ddev mysqlworkbench`. |

docs/users/extending-commands.md

@@ -1,4 +1,4 @@
-<h1>Extending ddev Commands</h1>
+## ddev Hooks
 
 Most ddev commands provide hooks to run tasks before or after the main command executes. To automate setup tasks specific to your project, define them in the project's config.yaml file.
 

mkdocs.yml

@@ -8,29 +8,28 @@ extra_javascript:
   - assets/fix-search.js
 markdown_extensions:
   - markdown.extensions.toc
-pages:
+nav:
   - 'Home': 'index.md'
-  - 'User Documentation':
+  - 'ddev Basics':
     - 'Using the CLI': 'users/cli-usage.md'
-    - 'Extending ddev Commands': 'users/extending-commands.md'
+    - 'ddev Hooks': 'users/extending-commands.md'
     - 'Using Developer Tools with ddev': 'users/developer-tools.md'
     - 'PHP Step Debugging': 'users/step-debugging.md'
-    - 'Extending ddev':
-      - '.ddev/config.yaml Options': 'users/extend/config_yaml.md'
-      - 'Additional Project Hostnames': 'users/extend/additional-hostnames.md'
-      - 'Extending and Customizing Environments': 'users/extend/customization-extendibility.md'
-      - 'Additional Services': 'users/extend/additional-services.md'
-      - 'Defining Custom Services': 'users/extend/custom-compose-files.md'
-      - 'Customizing Docker Images': 'users/extend/customizing-images.md'
-      - 'Custom Commands': 'users/extend/custom-commands.md'
-      - 'In-container Configuration': 'users/extend/in-container-configuration.md'
-    - 'Integration with Hosting Providers':
-      - 'Pantheon': 'users/providers/pantheon.md'
-      - 'DDEV-Live': 'users/providers/drud-s3.md'
     - 'Troubleshooting': 'users/troubleshooting.md'
     - 'Docker Installation': 'users/docker_installation.md'
     - 'Performance': 'users/performance.md'
     - 'Uninstalling DDEV-Local': 'users/uninstall.md'
     - 'Frequently-Asked Questions (FAQ)': 'users/faq.md'
+    - '.ddev/config.yaml Options': 'users/extend/config_yaml.md'
+    - 'Additional Project Hostnames': 'users/extend/additional-hostnames.md'
+  - 'Extending ddev':
+    - 'Extending and Customizing Environments': 'users/extend/customization-extendibility.md'
+    - 'Additional Services': 'users/extend/additional-services.md'
+    - 'Defining Custom Services': 'users/extend/custom-compose-files.md'
+    - 'Customizing Docker Images': 'users/extend/customizing-images.md'
+    - 'Custom Commands': 'users/extend/custom-commands.md'
+    - 'In-container Configuration': 'users/extend/in-container-configuration.md'
+  - 'Integration with Hosting Providers':
+    - 'Pantheon': 'users/providers/pantheon.md'
   - 'Developer Documentation':
     - 'Building, Testing, and Contributing': 'developers/building-contributing.md'