Merge pull request #6306 from fatherlinux/master

[CI:DOCS] Docs revamp.

8 files changed, 171 insertions, 19 deletions

diff --git a/docs/source/Commands.rst b/docs/source/Commands.rst
index 028f03429..e3dbf8ecd 100644
--- a/docs/source/Commands.rst
+++ b/docs/source/Commands.rst
@@ -1,3 +1,5 @@
+.. include:: includes.rst
+
 Commands
 ========
 
diff --git a/docs/source/Introduction.rst b/docs/source/Introduction.rst
index c516b3317..a1f9d605e 100644
--- a/docs/source/Introduction.rst
+++ b/docs/source/Introduction.rst
@@ -1,2 +1,106 @@
+.. include:: includes.rst
+
 Introduction
-============
+==================================
+Containers_ simplify the consumption of applications with all of their dependencies and default configuration files. Users test drive or deploy a new application with one or two commands instead of following pages of installation instructions. Here's how to find your first `Container Image`_::
+
+    podman search busybox
+
+Output::
+
+    INDEX       NAME                                DESCRIPTION                                       STARS   OFFICIAL   AUTOMATED
+    docker.io   docker.io/library/busybox           Busybox base image.                               1882    [OK]
+    docker.io   docker.io/radial/busyboxplus        Full-chain, Internet enabled, busybox made f...   30                 [OK]
+    docker.io   docker.io/yauritux/busybox-curl     Busybox with CURL                                 8
+    ...
+
+The previous command returned a list of publicly available container images on DockerHub. These container images are easy to consume, but of differing levels of quality and maintenance. Let’s use the first one listed because it seems to be well maintained.
+
+To run the busybox container image, it’s just a single command::
+
+    podman run -it docker.io/library/busybox
+
+Output::
+
+    / #
+
+You can poke around in the busybox container for a while, but you’ll quickly find that running small container with a few Linux utilities in it provides limited value, so exit out::
+
+    exit
+
+There’s an old saying that “nobody runs an operating system just to run an operating system” and the same is true with containers. It’s the workload running on top of an operating system or in a container that’s interesting and valuable.
+
+Sometimes we can find a publicly available container image for the exact workload we’re looking for and it will already be packaged exactly how we want. But, more often than not, there’s something that we want to add, remove, or customize. It could be as simple as a configuration setting for security or performance, or as complex as adding a complex workload. Either way, containers make it fairly easy to make the changes we need.
+
+Container Images aren’t actually images, they’re repositories often made up of multiple layers. These layers can easily be added, saved, and shared with others by using a Containerfile (Dockerfile). This single file often contains all the instructions needed to build the new and can easily be shared with others publicly using tools like GitHub.
+
+Here's an example of how to build an Nginx web server on top of a Debian base image using the Dockerfile maintained by Nginx and published in GitHub::
+
+    podman build -t nginx https://git.io/Jf8ol
+
+Once, the image build completes, it’s easy to run the new image from our local cache::
+
+    podman run -d -p 8080:80 nginx
+    curl localhost:8080
+
+Output::
+
+    ...
+    <p><em>Thank you for using nginx.</em></p>
+    ...
+
+Building new images is great, but sharing our work with others let’s them review our work, critique how we built them, and offer improved versions. Our newly built Nginx image could be published at quay.io or docker.io to share it with the world. Everything needed to run the Nginx application is provided in the container image. Others could easily pull it down and use it, or make improvements to it.
+
+Standardizing on container images and `Container Registries`_ enable a new level of collaboration through simple consumption. This simple consumption model is possible because every major Container Engine and Registry Server uses the Open Containers Initiative (OCI_) format. This allows users to find, run, build, share and deploy containers anywhere they want. Podman and other `Container Engines`_ like CRI-O, Docker, or containerd can create and consume container images from docker.io, quay.io, an on premise registry or even one provided by a cloud provider. The OCI image format facilitates this ecosystem through a single standard.
+
+For example, if we wanted to share our newly built Nginx container image on quay.io it’s easy. First log in to quay::
+
+    podman login quay.io
+Input::
+
+    Username: USERNAME
+    Password: ********
+    Login Succeeded!
+
+Nex, tag the image so that we can push it into our user account::
+
+    podman tag localhost/nginx quay.io/USERNAME/nginx
+
+Finally, push the image::
+
+    podman push quay.io/USERNAME/nginx
+
+Output::
+
+    Getting image source signatures
+    Copying blob 38c40d6c2c85 done
+    Copying blob fee76a531659 done
+    Copying blob c2adabaecedb done
+    Copying config 7f3589c0b8 done
+    Writing manifest to image destination
+    Copying config 7f3589c0b8 done
+    Writing manifest to image destination
+    Storing signatures
+
+Notice that we pushed four layers to our registry and now it’s available for others to share. Take a quick look::
+
+    podman inspect quay.io/USERNAME/nginx
+
+Output::
+
+    [
+        {
+            "Id": "7f3589c0b8849a9e1ff52ceb0fcea2390e2731db9d1a7358c2f5fad216a48263",
+            "Digest": "sha256:7822b5ba4c2eaabdd0ff3812277cfafa8a25527d1e234be028ed381a43ad5498",
+            "RepoTags": [
+                "quay.io/USERNAME/nginx:latest",
+    ...
+
+To summarize, Podman makes it easy to find, run, build and share containers.
+
+* Find: whether finding a container on dockerhub.io or quay.io, an internal registry server, or directly from a vendor, a couple of `podman search`_, and `podman pull`_ commands make it easy
+* Run: it's easy to consume pre-built images with everything needed to run an entire application, or start from a Linux distribution base image with the `podman run`_ command
+* Build: creating new layers with small tweaks, or major overhauls is easy with `podman build`
+* Share: Podman let’s you push your newly built containers anywhere you want with a single `podman push`_ command
+
+For more instructions on use cases, take a look at our :doc:`Tutorials` page.
diff --git a/docs/source/Reference.rst b/docs/source/Reference.rst
index c6a131bc7..d194c55a3 100644
--- a/docs/source/Reference.rst
+++ b/docs/source/Reference.rst
@@ -1,4 +1,10 @@
+.. include:: includes.rst
+
 Reference
 =========
 
-Check out our new in-development `API documentation <_static/api.html>`_
+To see full screen version please visit: `API documentation <https://docs.podman.io/en/latest/_static/api.html>`_
+
+.. raw:: html
+
+    <iframe src="_static/api.html" allowfullscreen="true" height="600px" width="120%"></iframe>
diff --git a/docs/source/Search.rst b/docs/source/Search.rst
new file mode 100644
index 000000000..a80c229f4
--- /dev/null
+++ b/docs/source/Search.rst
@@ -0,0 +1,18 @@
+.. include:: includes.rst
+
+Search
+==================================
+
+.. raw:: html
+
+    <p>
+    From here you can search these documents. Enter your search
+    words into the box below and click "search". Note that the search
+    function will automatically search for all of the words. Pages
+    containing fewer words won't appear in the result list.
+    </p>
+    <form action="/en/latest/search.html" method="get" _lpchecked="1">
+    <input type="text" name="q" value="">
+    <input type="submit" value="search">
+    <span id="search-progress" style="padding-left: 10px"></span>
+    </form>
diff --git a/docs/source/Tutorials.rst b/docs/source/Tutorials.rst
index 85ae59131..0c013c244 100644
--- a/docs/source/Tutorials.rst
+++ b/docs/source/Tutorials.rst
@@ -1,4 +1,12 @@
+.. include:: includes.rst
+
 Tutorials
 =========
+Here are a number of useful tutorials to get you up and running with Podman. If you are familiar with the Docker `Container Engine`_ the command in Podman_ should be quite familiar. If are brand new to containers, take a look at our `Introduction`.
 
-`Podman Tutorials on GitHub <https://github.com/containers/libpod/tree/master/docs/tutorials>`_
+* `Basic Setup and Use of Podman <https://github.com/containers/libpod/blob/master/docs/tutorials/podman_tutorial.md>`_: Learn how to setup Podman and perform some basic commands with the utility.
+* `Basic Setup and Use of Podman in a Rootless environment <https://github.com/containers/libpod/blob/master/docs/tutorials/rootless_tutorial.md>`_: The steps required to setup rootless Podman are enumerated.
+* `Podman Mac Client tutorial <https://github.com/containers/libpod/blob/master/docs/tutorials/mac_client.md>`_: Special setup for running the Podman remote client on a Mac and connecting to Podman running on a Linux VM are documented.
+* `How to sign and distribute container images using Podman <https://github.com/containers/libpod/blob/master/docs/tutorials/image_signing.md>`_: Learn how to setup and use image signing with Podman.
+* `Podman remote-client tutorial <https://github.com/containers/libpod/blob/master/docs/tutorials/remote_client.md>`_: A brief how-to on using the Podman remote-client.
+* `How to use libpod for custom/derivative projects <https://github.com/containers/libpod/blob/master/docs/tutorials/podman-derivative-api.md>`_: How the libpod API can be used within your own project.
diff --git a/docs/source/_static/api.html b/docs/source/_static/api.html
index 08f55b620..8b9d66e0d 100644
--- a/docs/source/_static/api.html
+++ b/docs/source/_static/api.html
@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <title>ReDoc</title>
+    <title>Reference</title>
     <!-- needed for adaptive design -->
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1">
diff --git a/docs/source/includes.rst b/docs/source/includes.rst
new file mode 100644
index 000000000..4794f454a
--- /dev/null
+++ b/docs/source/includes.rst
@@ -0,0 +1,19 @@
+.. highlight:: bash
+.. _Podman: http://podman.io
+.. _OCI: https://www.opencontainers.org/
+.. _Container Engine: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.6yt1ex5wfo3l
+.. _Container Engines: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.6yt1ex5wfo3l
+.. _Container Runtime: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.6yt1ex5wfo55
+.. _Container: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.j2uq93kgxe0e
+.. _Containers: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.j2uq93kgxe0e
+.. _Container Image: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.dqlu6589ootw
+.. _Container Images: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.dqlu6589ootw
+.. _Container Registry: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.4cxnedx7tmvq
+.. _Container Registries: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.4cxnedx7tmvq
+.. _libpod: https://github.com/containers/libpod
+.. _podman search: http://docs.podman.io/en/latest/markdown/podman-search.1.html
+.. _podman pull: http://docs.podman.io/en/latest/markdown/podman-pull.1.html
+.. _podman run: http://docs.podman.io/en/latest/markdown/podman-run.1.html
+.. _podman build: http://docs.podman.io/en/latest/markdown/podman-build.1.html
+.. _podman push: http://docs.podman.io/en/latest/markdown/podman-push.1.html
+.. image:: https://github.com/containers/libpod/blob/master/logo/podman-logo.png?raw=true
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 9dd61a6a6..9cc8e7af8 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,10 +1,14 @@
-.. Podman documentation master file, created by
-   sphinx-quickstart on Tue Oct 22 15:20:30 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. include:: includes.rst
 
-Welcome to Podman's documentation!
+What is Podman?
 ==================================
+Podman_ is a daemonless, open source, Linux native tool designed to make it easy to find, run, build, share and deploy applications using Open Containers Initiative (OCI_) Containers_ and `Container Images`_. Podman provides a command line interface (CLI) familiar to anyone who has used the Docker `Container Engine`_. Most users can simply alias Docker to Podman (`alias docker=podman`) without any problems. Similiar other common `Container Engines`_ (Docker, CRI-O, containerd), Podman relies on an OCI compliant `Container Runtime`_ (runc, crun, runv, etc) to interface with the operating system and create the running containers.This makes the running containers created by Podman nearly indistinguishable from those created by any other common container engine.
+
+Containers under the control of Podman can either be run by root or by a non-privileged user. Podman manages the entire container ecosystem which includes pods, containers, container images, and container volumes using the libpod_ library. Podman specializes in all of the commands and functions that help you to maintain and modify OCI container images, such as pulling and tagging. It allows you to create, run, and maintain those containers and container images in a production environment.
+
+The Podman service runs only on Linux platforms, however a REST API and clients are currently under development which will allow Mac and Windows platforms to call the service. There is currently a Varlink based remote client which runs on Mac or Windows platforms that allows the remote client to talk to the Podman server on a Linux platform. In addition to those clients, there is also a Mac client. NOTE: the Varlink remote client will be deprecated after the REST API is completed.
+
+If you are completely new to containers, we recommend that you check out the :doc:`Introduction`. For power users or those comming from Docker, check out our :doc:`Tutorials`. For advanced users and contributors, you can get very detailed information about the Podman CLI by looking our :doc:`Commands` page. Finally, for Developers looking at how to interact with the Podman API, please see our API documentation :doc:`Reference`.
 
 .. toctree::
    :maxdepth: 2
@@ -14,13 +18,4 @@ Welcome to Podman's documentation!
    Commands
    Reference
    Tutorials
-
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   Search