[lxc-devel] [pylxd/master] Fix documentation
jpic on Github
lxc-bot at linuxcontainers.org
Thu May 19 16:22:47 UTC 2016
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 598 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20160519/5607e19a/attachment.bin>
-------------- next part --------------
From 9b643faac9313900f3cf1723220f56ad735af941 Mon Sep 17 00:00:00 2001
From: jpic <jamespic at gmail.com>
Date: Thu, 19 May 2016 18:18:24 +0200
Subject: [PATCH] Fix documentation
Convert README from markdown to rst format, because the
docs/source/readme.rst file expect it, and also because it will render
better on PyPi without additionnal configuration.
Also, added notes about documentation and tests in the README, and
extracted its contents into the doc/ directory.
---
README.md | 60 ---------------------------------------------
README.rst | 36 +++++++++++++++++++++++++++
doc/source/index.rst | 2 +-
doc/source/installation.rst | 14 +++++++----
doc/source/readme.rst | 1 -
doc/source/usage.rst | 32 +++++++++++++++++++++---
setup.cfg | 2 +-
7 files changed, 75 insertions(+), 72 deletions(-)
delete mode 100644 README.md
create mode 100644 README.rst
delete mode 100644 doc/source/readme.rst
diff --git a/README.md b/README.md
deleted file mode 100644
index 6a01b6b..0000000
--- a/README.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# pylxd [](https://travis-ci.org/lxc/pylxd)
-
-A Python library for interacting with the LXD REST API.
-
-## Getting started with pylxd
-
-If you're running on Ubuntu Wily or greater:
-
- sudo apt-get install python-pylxd lxd
-
-otherwise you can track LXD development on other Ubuntu releases:
-
- sudo add-apt-repository ppa:ubuntu-lxc/lxd-git-master && sudo apt-get update
- sudo apt-get install lxd
-
-and install pylxd using pip:
-
- pip install pylxd
-
-## First steps
-
-Once you have pylxd installed, you're ready to start interacting with LXD:
-
-```python
-import uuid
-from pylxd import api
-
-# Let's pick a random name, avoiding clashes
-CONTAINER_NAME = str(uuid.uuid1())
-
-lxd = api.API()
-
-try:
- lxd.container_defined(CONTAINER_NAME)
-except Exception as e:
- print("Container does not exist: %s" % e)
-
-config = {'name': CONTAINER_NAME,
- 'source': {'type': 'none'}}
-lxd.container_init(config)
-if lxd.container_defined(CONTAINER_NAME):
- print("Container is running")
-else:
- print("Whoops - please report a bug!")
-containers = lxd.container_list()
-for x in containers:
- lxd.container_destroy(x)
-```
-
-## Bug reports
-
-Bug reports can be filed at https://github.com/lxc/pylxd/issues/new
-
-## Support and discussions
-
-We use the LXC mailing-lists for developer and user discussions, you can
-find and subscribe to those at: https://lists.linuxcontainers.org
-
-If you prefer live discussions, some of us also hang out in
-[#lxcontainers](http://webchat.freenode.net/?channels=#lxcontainers) on irc.freenode.net.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..56e8d2b
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,36 @@
+pylxd
+~~~~~
+
+.. image:: https://travis-ci.org/lxc/pylxd.svg?branch=master
+ :target: https://travis-ci.org/lxc/pylxd
+
+A Python library for interacting with the LXD REST API.
+
+Documentation
+=============
+
+Documentation is maintained in the doc directory. It can be built with the
+`python setup.py build_sphinx` command.
+
+Tests
+=====
+
+Tests can be run with the tox command:
+
+ tox -e integration
+
+Bug reports
+===========
+
+Bug reports can be filed on the `GitHub repository
+<https://github.com/lxc/pylxd/issues/new>`_.
+
+Support and discussions
+=======================
+
+We use the `LXC mailing-lists for developer and user discussions
+<https://lists.linuxcontainers.org>`_.
+
+If you prefer live discussions, some of us also hang out in
+`#lxcontainers
+<http://webchat.freenode.net/?channels=#lxcontainers>`_ on irc.freenode.net.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 49960a7..0e5bc1d 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -4,7 +4,7 @@
contain the root `toctree` directive.
Welcome to pylxd's documentation!
-========================================================
+=================================
Contents:
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index 283c9e3..bdf21a7 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -2,11 +2,15 @@
Installation
============
-At the command line::
+If you're running on Ubuntu Wily or greater::
- $ pip install pylxd
+ sudo apt-get install python-pylxd lxd
-Or, if you have virtualenvwrapper installed::
+Otherwise you can track LXD development on other Ubuntu releases::
- $ mkvirtualenv pylxd
- $ pip install pylxd
\ No newline at end of file
+ sudo add-apt-repository ppa:ubuntu-lxc/lxd-git-master && sudo apt-get update
+ sudo apt-get install lxd
+
+Or install pylxd using pip::
+
+ pip install pylxd
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index 38ba804..0000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../README.rst
\ No newline at end of file
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 37fd414..bd0155a 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -1,7 +1,31 @@
-========
+=====
Usage
-========
+=====
-To use pylxd in a project::
+Once you have pylxd installed, you're ready to start interacting with LXD:
- import pylxd
\ No newline at end of file
+.. code-block:: python
+
+ import uuid
+ from pylxd import api
+
+ # Let's pick a random name, avoiding clashes
+ CONTAINER_NAME = str(uuid.uuid1())
+
+ lxd = api.API()
+
+ try:
+ lxd.container_defined(CONTAINER_NAME)
+ except Exception as e:
+ print("Container does not exist: %s" % e)
+
+ config = {'name': CONTAINER_NAME,
+ 'source': {'type': 'none'}}
+ lxd.container_init(config)
+ if lxd.container_defined(CONTAINER_NAME):
+ print("Container is running")
+ else:
+ print("Whoops - please report a bug!")
+ containers = lxd.container_list()
+ for x in containers:
+ lxd.container_destroy(x)
diff --git a/setup.cfg b/setup.cfg
index 913d330..3ee93ba 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -3,7 +3,7 @@ name = pylxd
summary = python library for lxd
version = 2.0.0
description-file =
- README.md
+ README.rst
author = Chuck Short
author-email = chuck.short at canonical.com
home-page = http://www.linuxcontainers.org
More information about the lxc-devel
mailing list