deploy docs to github pages

fix freebsd#35

CONTRIBUTING.md

@@ -73,4 +73,4 @@ x = max(
 
 ## Documentation for Read The Docs
 
-If you wish to update some of our [documentation](http://iocage.readthedocs.org), you only need to submit a PR for the files you change in iocage/doc/source. They will automatically be updated when the changes are merged.
+If you wish to update some of our [documentation](https://freebsd.github.io/iocage/), you only need to submit a PR for the files you change in iocage/doc/source. They will automatically be updated when the changes are merged.

PULL_REQUEST_TEMPLATE.md

@@ -1,4 +1,4 @@
 Make sure to follow and check these boxes before submitting a PR! Thank you.
 
 - [ ] Explain the feature
-- [ ] Read [CONTRIBUTING.md](https://github.com/iocage/iocage/blob/master/CONTRIBUTING.md)
+- [ ] Read [CONTRIBUTING.md](https://github.com/freebsd/iocage/blob/master/CONTRIBUTING.md)

README.md

@@ -50,9 +50,7 @@ This repository replaces `iocage_legacy`. To upgrade to the current version:
 
 ## Links
 
-- **[iocage Project Website](https://iocage.github.io/)**
-- **[Documentation](http://iocage.readthedocs.org/en/latest/index.html)**
-- **[Mailing list](https://groups.google.com/forum/#!forum/iocage)**
+- **[iocage Project Website](https://freebsd.github.io/iocage/)**
 
 ## WARNING:
 - Some features of the previous iocage_legacy are either being dropped or simply not ported yet, feel free to open an issue asking about your favorite feature. But please search before opening a new one. PR's welcome for any feature you want!

doc/.gitignore

@@ -0,0 +1 @@
+build

doc/Makefile

@@ -53,6 +53,8 @@ html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@rm -rf ../docs
+	cp -r $(BUILDDIR)/html ../docs
 
 .PHONY: dirhtml
 dirhtml:

docs/_sources/advanced-use.rst.txt

@@ -0,0 +1,312 @@
+.. index:: Advance Usage
+.. _Advanced Usage:
+
+Advanced Usage
+==============
+
+.. index:: Clones
+.. _Clones:
+
+Clones
+------
+
+When a jail is cloned, iocage creates a ZFS clone filesystem.
+Essentially, clones are cheap, lightweight, and writable snapshots.
+
+A clone depends on its source snapshot and filesystem. To destroy the
+source jail and preserve its clones, the clone must be promoted first.
+
+.. index:: Create clones
+.. _Create a Clone:
+
+Create a Clone
+++++++++++++++
+
+To clone **www01** to **www02**, run:
+
+:samp:`# iocage clone www01 --name www02`
+
+Clone a jail from an existing snapshot with:
+
+:samp:`# iocage clone www01@snapshotname --name www03`
+
+.. index:: Promote a Clone
+.. _Promoting a Clone:
+
+Promoting a Clone
++++++++++++++++++
+
+.. warning:: This functionality isn't fully added to iocage, and may not
+   function as expected.
+
+**To promote a cloned jail, run:**
+
+:command:`iocage promote [UUID | NAME]`
+
+This reverses the *clone* and *source* jail relationship. The clone
+becomes the source and the source jail is demoted to a clone.
+
+**The demoted jail can now be removed:**
+
+:command:`iocage destroy [UUID | NAME]`
+
+.. index:: Updating Jails
+.. _Updating Jails:
+
+Updating Jails
+--------------
+
+Updates are handled with the freebsd-update(8) utility. Jails can be
+updated while they are stopped or running.
+
+.. note:: The command :command:`iocage update [UUID | NAME]`
+   automatically creates a backup snapshot of the jail given.
+
+To create a backup snapshot manually, run:
+
+:command:`iocage snapshot -n [snapshotname] [UUID | NAME]`
+
+To update a jail to latest patch level, run:
+
+:command:`iocage update [UUID | NAME]`
+
+When updates are finished and the jail appears to function properly,
+remove the snapshot:
+
+:command:`iocage snapremove [UUID|NAME]@[snapshotname]`
+
+To test updating without affecting a jail, create a clone and update the
+clone the same way as outlined above.
+
+To clone a jail, run:
+
+:command:`iocage clone [UUID|NAME] --name [testupdate]`
+
+.. note:: The **[-n | --name]** flag is optional. :command:`iocage`
+   assigns an UUID to the jail if **[-n | --name]** is not used.
+
+.. index:: Upgrade Jails
+.. _Upgrading Jails:
+
+Upgrading Jails
+---------------
+
+Upgrades are handled with the freebsd-update(8) utility. By default, the
+user must supply the new RELEASE for the jail's upgrade. For example:
+
+:samp:`# iocage upgrade examplejail -r 11.0-RELEASE`
+
+Tells jail *examplejail* to upgrade its RELEASE to *11.0-RELEASE*.
+
+.. note:: It is recommended to keep the iocage host and jails RELEASE
+   synchronized.
+
+To upgrade a jail to the host's RELEASE, run:
+
+:command:`iocage upgrade -r [11.1-RELEASE] [UUID | NAME]`
+
+This upgrades the jail to the same RELEASE as the host. This method also
+applies to basejails.
+
+.. index:: Auto-Boot
+.. _AutoBoot:
+
+Auto-boot
+---------
+
+Make sure :command:`iocage_enable="YES"` is set in :file:`/etc/rc.conf`.
+
+To enable a jail to auto-boot during a system boot, simply run:
+
+:samp:`# iocage set boot=on UUID|NAME`
+
+.. note:: Setting :command:`boot=on` during jail creation starts the
+   jail after the jail is created.
+
+.. index:: Boot Priority
+.. _Boot Priority:
+
+Boot Priority
++++++++++++++
+
+Boot order can be specified by setting the priority value:
+
+:command:`iocage set priority=[20] [UUID|NAME]`
+
+*Lower* values are higher in the boot priority.
+
+.. index:: Depends Property
+.. _Depends Property:
+
+Depends Property
+++++++++++++++++
+
+Use the :literal:`depends` property to require other jails to start
+before this one. It is space delimited. Jails listed as dependents
+also wait to start if those jails have listed :literal:`depends`.
+
+Example: :command:`iocage set depends=“foo bar” baz`
+
+.. index:: Snapshot Management
+.. _Snapshot Management:
+
+Snapshot Management
+-------------------
+
+iocage supports transparent ZFS snapshot management out of the box.
+Snapshots are point-in-time copies of data, a safety point to which a
+jail can be reverted at any time. Initially, snapshots take up almost no
+space, as only changing data is recorded.
+
+You may use **ALL** as a target jail name for these commands if you want to target all jails at once.
+
+List snapshots for a jail:
+
+:command:`iocage snaplist [UUID|NAME]`
+
+Create a new snapshot:
+
+:command:`iocage snapshot [UUID|NAME]`
+
+This creates a snapshot based on the current time.
+
+:command:`iocage snapshot [UUID|NAME] -n [SNAPSHOT NAME]`
+
+This creates a snapshot with the given name.
+
+Delete a snapshot:
+
+:command:`iocage snapremove [UUID|NAME] -n [SNAPSHOT NAME]`
+
+Delete all snapshots from a jail (requires `-f / --force`):
+
+:command:`iocage snapremove [UUID|NAME] -n ALL -f`
+
+.. index:: Resource Limits
+.. _Resource Limits:
+
+Resource Limits (Legacy ONLY)
+-----------------------------
+
+.. warning:: This functionality is only available for legacy versions of
+   :command:`iocage`. It is not yet implemented in the current version.
+   This applies to all subsections of *Resource Limits*.
+
+:command:`iocage` can enable optional resource limits for a jail. The
+outlined procedure here is meant to provide a starting point for the
+user.
+
+.. index:: Limit Cores or Threads
+.. _Limit Cores or Threads:
+
+Limit Cores or Threads
+++++++++++++++++++++++
+
+Limit a jail to a single thread or core #1:
+
+:command:`iocage set cpuset=1 [UUID|TAG]`
+:command:`iocage start [UUID|TAG]`
+
+.. index:: List Applied Rules
+.. _List Applied Rules:
+
+List Applied Limits
++++++++++++++++++++
+
+List applied limits:
+
+:command:`iocage limits [UUID|TAG]`
+
+.. index:: Limit DRAM Usage
+.. _Limit DRAM Usage:
+
+Limit DRAM use
+++++++++++++++
+
+This example limits a jail to using 4 Gb DRAM memory (limiting RSS
+memory use can be done on-the-fly):
+
+:samp:`# iocage set memoryuse=4G:deny examplejail`
+
+.. index:: Turn on Resource Limits
+.. _Turn on Resource Limits:
+
+Turn on Resource Limits
++++++++++++++++++++++++
+
+Turn on resource limiting for a jail with:
+
+:command:`iocage set rlimits=on [UUID|TAG]`
+
+.. index:: Apply Limits
+.. _Apply Limits:
+
+Apply limits
+++++++++++++
+
+Apply limits to a running jail with:
+
+:command:`iocage cap [UUID | TAG]`
+
+.. index:: Check Limits
+.. _Check Limits:
+
+Check Limits
+++++++++++++
+
+Check the currently active limits on a jail with:
+
+:command:`iocage limits [UUID | TAG]`
+
+.. index:: Limit CPU Usage by Percentage
+.. _Limit CPU Usage by Percentage:
+
+Limit CPU Usage by %
+++++++++++++++++++++
+
+In this example, :command:`iocage` limits *testjail* CPU execution to
+20%, then applies the limitation to the active jail:
+
+:samp:`# iocage set pcpu=20:deny testjail`
+:samp:`# iocage cap testjail`
+
+Double check the jail's current limits to confirm the functionality:
+
+:samp:`# iocage limits testjail`
+
+.. index:: Automatic Package Installation
+.. _Automatic Package Installation:
+
+Automatic Package Installation
+------------------------------
+
+Packages can be installed automatically at creation time!
+
+Use the [-p | --pkglist] option at creation time, which needs to point
+to a JSON file containing one package name per line.
+
+.. note:: An Internet connection is required for automatic package
+   installations, as :command:`pkg install` obtains packages from online
+   repositories.
+
+Create a :file:`pkgs.json` file and add package names to it.
+
+:file:`pkgs.json`:
+
+.. code-block:: json
+
+   {
+       "pkgs": [
+       "nginx",
+       "tmux"
+       ]
+   }
+
+Now, create a jail and supply :file:`pkgs.json`:
+
+:command:`iocage create -r [RELEASE] -p [path-to/pkgs.json] -n [NAME]`
+
+.. note:: The **[-n | --name]** flag is optional. :command:`iocage`
+   assigns an UUID to the jail if **[-n | --name]** is not used.
+
+This installs **nginx** and **tmux** in the newly created jail.