diff --git a/README.rst b/README.rst index bd3017f..038129f 100644 --- a/README.rst +++ b/README.rst @@ -29,7 +29,7 @@ Change to the root directory and run:: For convenience this package contains a [makefile](makefile) with this and other often used commands. Should you wish too, you can use the -shorthand: +shorthand:: $ make install @@ -77,7 +77,7 @@ configured in ``setup.py`` to run the tests:: This is just calling ``sage -t`` with appropriate flags. -Shorthand: +Shorthand:: $ make test @@ -90,19 +90,19 @@ The documentation of the package can be generated using Sage's $ cd docs $ sage -sh -c "make html" -Shorthand: +Shorthand:: $ make doc For this to work on your own package, make sure you follow the same structure as we do here: - * Create a ``docs`` folder containing the exact same ``Makefile`` and a ``source`` - folder. - * Copy and paste the ``docs/source/conf.py`` file from this package and update - the few project specific variables at the beginning of the file. - * Create an ``index.rst`` file as well as a ``.rst`` file for each - module you want on the documentation. +* Create a ``docs`` folder containing the exact same ``Makefile`` and a ``source`` + folder. +* Copy and paste the ``docs/source/conf.py`` file from this package and update + the few project specific variables at the beginning of the file. +* Create an ``index.rst`` file as well as a ``.rst`` file for each + module you want on the documentation. Travis CI integration --------------------- @@ -124,14 +124,14 @@ versions used. Automatically deploying documentation to GitHub pages using Travis CI --------------------------------------------------------------------- - * First do the steps described above to enable Travis CI integration - of your GitHub-hosted project. - - * If you don't already have GitHub pages for your project: Create and - checkout a branch ``gh-pages`` in your repository and put an empty - file ``.nojekyll`` in it. (See - https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/):: - Commit it and push it to GitHub:: +* First do the steps described above to enable Travis CI integration + of your GitHub-hosted project. + +* If you don't already have GitHub pages for your project: Create and + checkout a branch ``gh-pages`` in your repository and put an empty + file ``.nojekyll`` in it (see + https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/). + Then commit it and push it to GitHub:: $ git clone --single-branch --depth 1 https://github.com/USER/PROJECT.git gh-pages $ cd gh-pages @@ -142,38 +142,38 @@ Automatically deploying documentation to GitHub pages using Travis CI $ git commit -m "Initial commit" $ git push -u origin gh-pages $ cd .. - - * (Back in your working copy:) Generate a new ssh key pair with an - empty passphrase:: + +* (Back in your working copy:) Generate a new ssh key pair with an + empty passphrase:: $ ssh-keygen -t dsa -f .travis_ci_gh_pages_deploy_key - * Add the public ssh key (contents of the file - ``.travis_ci_gh_pages_deploy_key.pub``) to your GitHub repository - as a deploy key (Settings/Deploy keys/Add deploy key). - Title: Key for deploying documentation to GitHub pages. - Check Allow write access. +* Add the public ssh key (contents of the file + ``.travis_ci_gh_pages_deploy_key.pub``) to your GitHub repository + as a deploy key (Settings/Deploy keys/Add deploy key). + Title: Key for deploying documentation to GitHub pages. + Check Allow write access. - * Install the Travis CI command-line client from - https://github.com/travis-ci/travis.rb:: +* Install the Travis CI command-line client from + https://github.com/travis-ci/travis.rb:: $ gem install travis - - * Log in to Travis CI using your GitHub credentials:: + +* Log in to Travis CI using your GitHub credentials:: $ travis login - - * Encrypt the private ssh key, add the decryption keys - as secure environment variables to Travis CI, and - add code to ``.travis.yml`` to decrypt it:: + +* Encrypt the private ssh key, add the decryption keys + as secure environment variables to Travis CI, and + add code to ``.travis.yml`` to decrypt it:: $ travis encrypt-file .travis_ci_gh_pages_deploy_key --add before_script - * Add the encrypted private ssh key to the repository:: +* Add the encrypted private ssh key to the repository:: $ git add .travis_ci_gh_pages_deploy_key.enc - * Have git ignore the other keys (and the gh-pages directory):: +* Have git ignore the other keys (and the gh-pages directory):: $ echo >> .gitignore $ echo "/.travis_ci_gh_pages_deploy_key" >> .gitignore @@ -181,19 +181,19 @@ Automatically deploying documentation to GitHub pages using Travis CI $ echo "/gh-pages" >> .gitignore $ git add .gitignore - * Optionally, edit ``.travis.yml`` to adjust variables ``DEPLOY_DOC_...`` +* Optionally, edit ``.travis.yml`` to adjust variables ``DEPLOY_DOC_...`` - * Commit all changes to GitHub. The Travis CI build should then run - automatically and deploy it:: +* Commit all changes to GitHub. The Travis CI build should then run + automatically and deploy it:: $ git add .travis.yml $ git commit -m "Deploy built documentation to GitHub" $ git push - - * The deployed documentation will be available at: - https://USER.github.io/PROJECT/ - This can be customized by changing ``DEPLOY_DOC_TO_DIRECTORY=/`` - to another directory in ``.travis.yml`` - For example, setting ``DEPLOY_DOC_TO_DIRECTORY=doc/html`` will make - the deployed documentation available at: - https://USER.github.io/PROJECT/doc/html/ + +* The deployed documentation will be available at: + https://USER.github.io/PROJECT/ + This can be customized by changing ``DEPLOY_DOC_TO_DIRECTORY=/`` + to another directory in ``.travis.yml`` + For example, setting ``DEPLOY_DOC_TO_DIRECTORY=doc/html`` will make + the deployed documentation available at: + https://USER.github.io/PROJECT/doc/html/