From 5efea525e08568d46877183463180f55130061be Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Wed, 28 Oct 2015 10:06:28 +1100 Subject: [PATCH] Split GitHub README from Sphinx index The root of the documentation tree has a different function to the short readme we want to display on GitHub, which now links to the main docs (or Bay12 thread, or IRC). It also renders properly on GitHub, and can use live-updating status badges because we don't expect it to work offline. --- CMakeLists.txt | 2 +- README.html | 6 +++--- README.md | 24 ++++++++++++++++++++++++ docs/conf.py | 2 +- README.rst => index.rst | 19 ++++++++----------- 5 files changed, 37 insertions(+), 16 deletions(-) create mode 100644 README.md rename README.rst => index.rst (83%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 20a964998..715744239 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -214,7 +214,7 @@ if (BUILD_DOCS) "*.lua" "*.rb" ) - set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst README.rst) + set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst index.rst) set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo") set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) diff --git a/README.html b/README.html index 481058eb4..325cd66f6 100644 --- a/README.html +++ b/README.html @@ -4,13 +4,13 @@ - + Page Redirection - If you are not redirected automatically, follow the link to the documentation. + Follow this link to the documentation. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 000000000..50769e0c5 --- /dev/null +++ b/README.md @@ -0,0 +1,24 @@ +#DFHack Readme + +[![Build Status](https://travis-ci.org/DFHack/dfhack.svg?branch=develop)] +(https://travis-ci.org/DFHack/dfhack) +[![Documentation Status](https://readthedocs.org/projects/dfhack/badge)] +(https://dfhack.readthedocs.org) +[![License](https://img.shields.io/badge/license-ZLib-blue.svg)] +(https://en.wikipedia.org/wiki/Zlib_License) +[![Github Issues](http://githubbadges.herokuapp.com/DFHack/dfhack/issues)] +(https://github.com/DFHack/dfhack/issues) +[![Open Pulls](http://githubbadges.herokuapp.com/DFHack/dfhack/pulls)] +(https://github.com/DFHack/dfhack/pulls) + +DFHack is a Dwarf Fortress memory access library, distributed with scripts +and plugins implementing a wide variety of useful functions and tools. + +The full documentation [is available online here](https://dfhack.readthedocs.org), +from the README.html page in the DFHack distribution, or as raw text in the `./docs` folder. +If you're an end-user, modder, or interested in contributing to DFHack - +go read those docs. + +If that's unclear or you need more help, try [the Bay12 forums thread] +(http://www.bay12forums.com/smf/index.php?topic=139553) or the #dfhack IRC +channel on freenode. diff --git a/docs/conf.py b/docs/conf.py index 0f608e30e..546f843c8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -130,7 +130,7 @@ source_suffix = '.rst' #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'README' +master_doc = 'index' # General information about the project. project = 'DFHack' diff --git a/README.rst b/index.rst similarity index 83% rename from README.rst rename to index.rst index dcf3fb905..a93660db3 100644 --- a/README.rst +++ b/index.rst @@ -1,5 +1,6 @@ +################################## Welcome to DFHack's documentation! -================================== +################################## Introduction ============ @@ -22,14 +23,8 @@ allows easier development of new tools. As an open-source project under `various copyleft licences `, contributions are welcome. -Documentation -============= -DFHack documentation is generated by Sphinx. Check out the table of contents -below, or the sources in the `docs folder`_! - -.. _`docs folder`: ./docs - -User Manual: +User Manual +=========== .. toctree:: :maxdepth: 2 @@ -38,7 +33,8 @@ User Manual: docs/Plugins docs/Scripts -Other Contents: +Other Contents +============== .. toctree:: :maxdepth: 1 @@ -47,7 +43,8 @@ Other Contents: LICENSE NEWS -For Developers: +For Developers +============== .. toctree:: :maxdepth: 1