From 5f3e1071c12d6999b93772d84c7d65119cd12eec Mon Sep 17 00:00:00 2001 From: Devyn Stott Date: Fri, 21 Apr 2017 10:58:05 -0700 Subject: [PATCH] docs(): Rename and refactor things so they are better --- README.md | 9 +++- mkdocs.yml | 5 ++- starter/README.md | 5 +++ starter/docs/README.md | 51 ----------------------- starter/docs/installation-instructions.md | 3 ++ starter/docs/quick-start.md | 3 ++ starter/docs/user_guide/article1.md | 3 -- starter/docs/user_guide/article2.md | 3 -- starter/index.md | 4 +- 9 files changed, 24 insertions(+), 62 deletions(-) create mode 100644 starter/README.md delete mode 100644 starter/docs/README.md create mode 100644 starter/docs/installation-instructions.md create mode 100644 starter/docs/quick-start.md delete mode 100644 starter/docs/user_guide/article1.md delete mode 100644 starter/docs/user_guide/article2.md diff --git a/README.md b/README.md index f921c72..bd4d33b 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ A starting spot for python projects. Embracing open source elements. [![Documentation status](https://readthedocs.org/projects/python-starter/badge/?version=latest)](http://python-starter.readthedocs.io/en/latest/) [![Build Status](https://travis-ci.org/SyntaxRules/python-starter.svg?branch=master)](https://travis-ci.org/SyntaxRules/python-starter) [![codecov](https://codecov.io/gh/SyntaxRules/python-starter/branch/master/graph/badge.svg)](https://codecov.io/gh/SyntaxRules/python-starter) +Documentation: http://python-starter.readthedocs.io/en/latest/ # Project Details @@ -14,7 +15,7 @@ This project follows the structure suggested in [Jan-Philip Gehrcke's Blog](http This project uses [Semver](http://semver.org/) as its versioning scheme. -## Tests. +## Tests Basic acceptance tests are in the tests folder. You can run these tests by running `python setup.py test`. The unit tests are in line with the code. You can run all the tests with `python -m pytest .`. @@ -25,3 +26,9 @@ Coverage is also determined by TravisCI and reported to [CodeCov](https://codeco ## Documentation Documentation is inline (like unit tests) and deployed with [Read the Docs](http://python-starter.readthedocs.io/en/latest/). When editing code, please include documentation for your changes. Add any new files to the `mkdocs.yml` file. The documentation is automatically built and installed. + +The documentation is found here: http://python-starter.readthedocs.io/en/latest/ + +You can test the docs locally by installing [mkdocs](http://www.mkdocs.org/) and running `mkdocs serve` in the root directory of the project source. This will launch a server locally that you can use to view what the docs will look like when deployed. The pages update automatically when changes are made. + +You can add a page to the documentation by editing the *mkdocs.yml* file in the source repo. See [Adding Pages](http://www.mkdocs.org/#adding-pages). \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index a47528b..8b26306 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,5 +5,6 @@ docs_dir: 'starter' pages: - 'Overview': 'index.md' - 'User Guide': - - 'Quick Start': 'docs/user_guide/article1.md' - - 'Service API': 'docs/user_guide/article2.md' \ No newline at end of file + - 'Quick Start': 'docs/quick-start.md' + - 'Installation Instructions': 'docs/installation-instructions.md' + - 'License': 'docs/license.md' \ No newline at end of file diff --git a/starter/README.md b/starter/README.md new file mode 100644 index 0000000..2eeb651 --- /dev/null +++ b/starter/README.md @@ -0,0 +1,5 @@ +# Starter source and documentation + +The source code for the documentation page is found in index.md (in this same directory). + +The source code for this repo is found in this folder. See the docs for more information. diff --git a/starter/docs/README.md b/starter/docs/README.md deleted file mode 100644 index d69f7a0..0000000 --- a/starter/docs/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# Documentation - -The documentation uses [mkdocs.org](http://mkdocs.org) to build and serve itself. This produces pretty HTML pages for external viewing and is compatible with ReadtheDocs.org. - -To generate a PDF of this documentation use: https://github.com/jgrassler/mkdocs-pandoc - -## Generating a PDF - -To generate a PDF from mkdocs use [mkdocs-pandoc](https://github.com/jgrassler/mkdocs-pandoc). - -To install it, perform the following steps: - -1. yum install fonts-lmodern lmodern pandoc texlive-base texlive-latex-extra texlive-fonts-recommended texlive-latex-recommended texlive-xetex -2. yum install texlive-latex texlive-pdfpages texlive-pdftex - - - -## Commands - -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs help` - Print this help message. - -## Project layout - - mkdocs.yml # The configuration file. - docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. - -.. Python-Starter documentation master file, created by - sphinx-quickstart on Thu Apr 13 16:29:44 2017. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to Python-Starter's documentation! -========================================== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/starter/docs/installation-instructions.md b/starter/docs/installation-instructions.md new file mode 100644 index 0000000..8a88fe4 --- /dev/null +++ b/starter/docs/installation-instructions.md @@ -0,0 +1,3 @@ +# Installation instructions + +This section covers advanced installations instructions, including how to build from source. \ No newline at end of file diff --git a/starter/docs/quick-start.md b/starter/docs/quick-start.md new file mode 100644 index 0000000..78c0e37 --- /dev/null +++ b/starter/docs/quick-start.md @@ -0,0 +1,3 @@ +# Quick Start + +To get started using this project: \ No newline at end of file diff --git a/starter/docs/user_guide/article1.md b/starter/docs/user_guide/article1.md deleted file mode 100644 index 1b42147..0000000 --- a/starter/docs/user_guide/article1.md +++ /dev/null @@ -1,3 +0,0 @@ -# User Guide - -This is the user guide. \ No newline at end of file diff --git a/starter/docs/user_guide/article2.md b/starter/docs/user_guide/article2.md deleted file mode 100644 index 49ed64f..0000000 --- a/starter/docs/user_guide/article2.md +++ /dev/null @@ -1,3 +0,0 @@ -# Service commands - -This is all about a service command. \ No newline at end of file diff --git a/starter/index.md b/starter/index.md index 5a96978..f5aa3e7 100644 --- a/starter/index.md +++ b/starter/index.md @@ -1,5 +1,5 @@ # Overview -This is the project overview +This is the overview page and the default index page of the documentation. -Wit foo bar \ No newline at end of file +For development details (i.e project structure, tests and versioning) see the README.md file in the src repository. \ No newline at end of file