Update README.md

README.md

@@ -3,7 +3,21 @@
 [![PyPI](https://img.shields.io/pypi/dm/phonopy.svg?maxAge=2592000)](https://pypi.python.org/pypi/phonopy)
 [![Build Status](https://travis-ci.org/atztogo/phonopy.svg?branch=master)](https://travis-ci.org/atztogo/phonopy)
 
-phonopy
-=======
+# Phonopy
 
-Phonon code. For the details, see http://atztogo.github.io/phonopy/
+Phonon code. Phonopy user documetation is found at http://atztogo.github.io/phonopy/
+
+## Mailing list for questions
+
+Usual phonopy questions should be sent to phonopy mailing list (https://sourceforge.net/p/phonopy/mailman/).
+
+## Development
+
+The development of phonopy is managed on the 'develop' branch of github phonopy repository.
+
+* Github issues is the place to discuss about phonopy issues.
+* Github pull request is the place to request merging source code.
+
+## Documentation
+
+Phonopy user documetation is written using python sphinx. The source files are stored in `doc` directory. Please see how to write the documentation at `doc/README.me`.

doc/README.md

@@ -13,3 +13,23 @@ make html
 * `conf.py` contains the sphinx setting confiuration.
 * `*.rst` are the usual sphinx documentation source and the filenames without `.rst` are the keys to link from toctree mainly in `index.rst`.
 * `*.inc` are the files included in the other `*.rst` files.
+
+## How to publish
+
+Web page files are copied to `gh-pages` branch. At the phonopy github top directory,
+```
+git checkout gh-pages
+rm -r .buildinfo .doctrees *
+```
+
+From the directory the sphinx doc is complied,
+```
+rsync -avh _build/ <phonopy-repository-directory>/
+```
+
+Again, at the phonopy github top directory,
+```
+git add .
+git commit -a -m "Update documentation ..."
+git push
+```