From 4c616a5733dfa98a0d1b557d679af255ddb9759b Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Sun, 17 Sep 2017 21:23:36 +0200 Subject: [PATCH] Move all documentation files to doc/ --- .github/CONTRIBUTING.asciidoc | 1 + MANIFEST.in | 2 +- README.asciidoc | 18 +++++++++--------- COPYING => doc/COPYING | 0 CHANGELOG.asciidoc => doc/changelog.asciidoc | 0 .../contributing.asciidoc | 0 FAQ.asciidoc => doc/faq.asciidoc | 2 +- doc/help/index.asciidoc | 6 +++--- INSTALL.asciidoc => doc/install.asciidoc | 0 misc/qutebrowser.nsi | 2 +- qutebrowser/html/backend-warning.html | 2 +- qutebrowser/utils/docutils.py | 2 +- scripts/asciidoc2html.py | 12 ++++-------- scripts/dev/Makefile-dmg | 2 +- .../data/downloads/mhtml/complex/complex.html | 2 +- .../data/downloads/mhtml/complex/complex.mht | 2 +- www/header.asciidoc | 8 ++++---- 17 files changed, 29 insertions(+), 32 deletions(-) create mode 120000 .github/CONTRIBUTING.asciidoc rename COPYING => doc/COPYING (100%) rename CHANGELOG.asciidoc => doc/changelog.asciidoc (100%) rename CONTRIBUTING.asciidoc => doc/contributing.asciidoc (100%) rename FAQ.asciidoc => doc/faq.asciidoc (99%) rename INSTALL.asciidoc => doc/install.asciidoc (100%) diff --git a/.github/CONTRIBUTING.asciidoc b/.github/CONTRIBUTING.asciidoc new file mode 120000 index 000000000..93e1056d8 --- /dev/null +++ b/.github/CONTRIBUTING.asciidoc @@ -0,0 +1 @@ +../doc/contributing.asciidoc \ No newline at end of file diff --git a/MANIFEST.in b/MANIFEST.in index 52beeab1e..f3cd7d5a0 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -11,7 +11,7 @@ graft misc/userscripts recursive-include scripts *.py *.sh include qutebrowser/utils/testfile include qutebrowser/git-commit-id -include COPYING doc/* README.asciidoc CONTRIBUTING.asciidoc FAQ.asciidoc INSTALL.asciidoc CHANGELOG.asciidoc +include doc/* include qutebrowser.desktop include requirements.txt include tox.ini diff --git a/README.asciidoc b/README.asciidoc index c7f3ebc48..1bb2feba8 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -9,7 +9,7 @@ qutebrowser // QUTE_WEB_HIDE image:icons/qutebrowser-64x64.png[qutebrowser logo] *A keyboard-driven, vim-like browser based on PyQt5 and Qt.* -image:https://img.shields.io/pypi/l/qutebrowser.svg?style=flat["license badge",link="https://github.com/qutebrowser/qutebrowser/blob/master/COPYING"] +image:https://img.shields.io/pypi/l/qutebrowser.svg?style=flat["license badge",link="https://github.com/qutebrowser/qutebrowser/blob/master/doc/COPYING"] image:https://img.shields.io/pypi/v/qutebrowser.svg?style=flat["version badge",link="https://pypi.python.org/pypi/qutebrowser/"] image:https://requires.io/github/qutebrowser/qutebrowser/requirements.svg?branch=master["requirements badge",link="https://requires.io/github/qutebrowser/qutebrowser/requirements/?branch=master"] image:https://travis-ci.org/qutebrowser/qutebrowser.svg?branch=master["Build Status", link="https://travis-ci.org/qutebrowser/qutebrowser"] @@ -36,7 +36,7 @@ Downloads --------- See the https://github.com/qutebrowser/qutebrowser/releases[github releases -page] for available downloads and the link:INSTALL.asciidoc[INSTALL] file for +page] for available downloads and the link:doc/install.asciidoc[INSTALL] file for detailed instructions on how to get qutebrowser running on various platforms. Documentation @@ -49,11 +49,11 @@ available: image:https://qutebrowser.org/img/cheatsheet-small.png["qutebrowser key binding cheatsheet",link="https://qutebrowser.org/img/cheatsheet-big.png"] * link:doc/quickstart.asciidoc[Quick start guide] * A https://www.shortcutfoo.com/app/dojos/qutebrowser[free training course] to remember those key bindings. -* link:FAQ.asciidoc[Frequently asked questions] +* link:doc/faq.asciidoc[Frequently asked questions] * link:doc/help/configuring.html[Configuring qutebrowser] -* link:CONTRIBUTING.asciidoc[Contributing to qutebrowser] -* link:INSTALL.asciidoc[INSTALL] -* link:CHANGELOG.asciidoc[Change Log] +* link:doc/contributing.asciidoc[Contributing to qutebrowser] +* link:doc/install.asciidoc[Installing qutebrowser] +* link:doc/changelog.asciidoc[Change Log] * link:doc/stacktrace.asciidoc[Reporting segfaults] * link:doc/userscripts.asciidoc[How to write userscripts] @@ -79,7 +79,7 @@ Contributions / Bugs -------------------- You want to contribute to qutebrowser? Awesome! Please read -link:CONTRIBUTING.asciidoc[the contribution guidelines] for details and +link:doc/contributing.asciidoc[the contribution guidelines] for details and useful hints. If you found a bug or have a feature request, you can report it in several @@ -129,8 +129,8 @@ The following libraries are optional: * http://asciidoc.org/[asciidoc] to generate the documentation for the `:help` command, when using the git repository (rather than a release). -See link:INSTALL.asciidoc[INSTALL] for directions on how to install qutebrowser -and its dependencies. +See link:doc/install.asciidoc[the documentation] for directions on how to +install qutebrowser and its dependencies. Donating -------- diff --git a/COPYING b/doc/COPYING similarity index 100% rename from COPYING rename to doc/COPYING diff --git a/CHANGELOG.asciidoc b/doc/changelog.asciidoc similarity index 100% rename from CHANGELOG.asciidoc rename to doc/changelog.asciidoc diff --git a/CONTRIBUTING.asciidoc b/doc/contributing.asciidoc similarity index 100% rename from CONTRIBUTING.asciidoc rename to doc/contributing.asciidoc diff --git a/FAQ.asciidoc b/doc/faq.asciidoc similarity index 99% rename from FAQ.asciidoc rename to doc/faq.asciidoc index 0fe340474..cfc16ec12 100644 --- a/FAQ.asciidoc +++ b/doc/faq.asciidoc @@ -216,7 +216,7 @@ Segfaults on Facebook, Medium, Amazon, ...:: visiting these sites. This is caused by various bugs in Qt which have been fixed in Qt 5.4. However Debian and Ubuntu are slow to adopt or upgrade some packages. On Debian Jessie, it's recommended to use the experimental - repos as described in https://github.com/qutebrowser/qutebrowser/blob/master/INSTALL.asciidoc#on-debian--ubuntu[INSTALL]. + repos as described in https://github.com/qutebrowser/qutebrowser/blob/master/doc/install.asciidoc#on-debian--ubuntu[the documentation]. + Since Ubuntu Trusty (using Qt 5.2.1), https://bugreports.qt.io/browse/QTBUG-42417?jql=component%20%3D%20WebKit%20and%20resolution%20%3D%20Done%20and%20fixVersion%20in%20(5.3.0%2C%20%225.3.0%20Alpha%22%2C%20%225.3.0%20Beta1%22%2C%20%225.3.0%20RC1%22%2C%205.3.1%2C%205.3.2%2C%205.4.0%2C%20%225.4.0%20Alpha%22%2C%20%225.4.0%20Beta%22%2C%20%225.4.0%20RC%22)%20and%20priority%20in%20(%22P2%3A%20Important%22%2C%20%22P1%3A%20Critical%22%2C%20%22P0%3A%20Blocker%22)[over diff --git a/doc/help/index.asciidoc b/doc/help/index.asciidoc index e8321f2ad..4edea719e 100644 --- a/doc/help/index.asciidoc +++ b/doc/help/index.asciidoc @@ -7,13 +7,13 @@ Documentation The following help pages are currently available: * link:../quickstart.html[Quick start guide] -* link:../../FAQ.html[Frequently asked questions] -* link:../../CHANGELOG.html[Change Log] +* link:../doc.html[Frequently asked questions] +* link:../changelog.html[Change Log] * link:commands.html[Documentation of commands] * link:configuring.html[Configuring qutebrowser] * link:settings.html[Documentation of settings] * link:../userscripts.html[How to write userscripts] -* link:../../CONTRIBUTING.html[Contributing to qutebrowser] +* link:../contributing.html[Contributing to qutebrowser] Getting help ------------ diff --git a/INSTALL.asciidoc b/doc/install.asciidoc similarity index 100% rename from INSTALL.asciidoc rename to doc/install.asciidoc diff --git a/misc/qutebrowser.nsi b/misc/qutebrowser.nsi index 8f815c391..bc0b90b1b 100644 --- a/misc/qutebrowser.nsi +++ b/misc/qutebrowser.nsi @@ -23,7 +23,7 @@ SetCompressor /solid lzma !define MUI_ICON "../icons/qutebrowser.ico" !define MUI_UNICON "../icons/qutebrowser.ico" -!insertmacro MUI_PAGE_LICENSE "..\COPYING" +!insertmacro MUI_PAGE_LICENSE "..\doc\COPYING" !insertmacro MUI_PAGE_DIRECTORY !insertmacro MUI_PAGE_INSTFILES !insertmacro MUI_UNPAGE_CONFIRM diff --git a/qutebrowser/html/backend-warning.html b/qutebrowser/html/backend-warning.html index 2b631d6a5..0ba8e95ee 100644 --- a/qutebrowser/html/backend-warning.html +++ b/qutebrowser/html/backend-warning.html @@ -50,7 +50,7 @@ the qute://settings page or caret browsing). {% elif distribution.version >= version('17.04') %} {{ install_webengine('python3-pyqt5.qtwebengine') }} {% elif distribution.version >= version('16.04') %} - QtWebEngine is only available in Ubuntu's repositories since 17.04, but you can install qutebrowser via tox with tox -e mkvenv-pypi to use the new backend. + QtWebEngine is only available in Ubuntu's repositories since 17.04, but you can install qutebrowser via tox with tox -e mkvenv-pypi to use the new backend. {% else %} Unfortunately, no easy way is known to install QtWebEngine on Ubuntu < 16.04. {{ please_open_issue() }} {% endif %} diff --git a/qutebrowser/utils/docutils.py b/qutebrowser/utils/docutils.py index 1991068f9..567451e05 100644 --- a/qutebrowser/utils/docutils.py +++ b/qutebrowser/utils/docutils.py @@ -63,7 +63,7 @@ class DocstringParser: """Generate documentation based on a docstring of a command handler. - The docstring needs to follow the format described in CONTRIBUTING. + The docstring needs to follow the format described in doc/contributing. Attributes: _state: The current state of the parser state machine. diff --git a/scripts/asciidoc2html.py b/scripts/asciidoc2html.py index 6c7fdaf6e..dbf03e2f6 100755 --- a/scripts/asciidoc2html.py +++ b/scripts/asciidoc2html.py @@ -40,13 +40,7 @@ class AsciiDoc: """Abstraction of an asciidoc subprocess.""" - FILES = [ - ('FAQ.asciidoc', 'qutebrowser/html/doc/FAQ.html'), - ('CHANGELOG.asciidoc', 'qutebrowser/html/doc/CHANGELOG.html'), - ('CONTRIBUTING.asciidoc', 'qutebrowser/html/doc/CONTRIBUTING.html'), - ('doc/quickstart.asciidoc', 'qutebrowser/html/doc/quickstart.html'), - ('doc/userscripts.asciidoc', 'qutebrowser/html/doc/userscripts.html'), - ] + FILES = ['faq', 'changelog', 'contributing', 'quickstart', 'userscripts'] def __init__(self, args): self._cmd = None @@ -80,7 +74,9 @@ class AsciiDoc: def _build_docs(self): """Render .asciidoc files to .html sites.""" - files = self.FILES[:] + files = [('doc/{}.asciidoc'.format(f), + 'qutebrowser/html/{}.html'.format(f)) + for f in self.FILES] for src in glob.glob('doc/help/*.asciidoc'): name, _ext = os.path.splitext(os.path.basename(src)) dst = 'qutebrowser/html/doc/{}.html'.format(name) diff --git a/scripts/dev/Makefile-dmg b/scripts/dev/Makefile-dmg index 0f699ea8b..e4711a038 100644 --- a/scripts/dev/Makefile-dmg +++ b/scripts/dev/Makefile-dmg @@ -21,7 +21,7 @@ NAME ?= qutebrowser SOURCE_DIR ?= . -SOURCE_FILES ?= dist/qutebrowser.app COPYING +SOURCE_FILES ?= dist/qutebrowser.app doc/COPYING TEMPLATE_DMG ?= template.dmg TEMPLATE_SIZE ?= 300m diff --git a/tests/end2end/data/downloads/mhtml/complex/complex.html b/tests/end2end/data/downloads/mhtml/complex/complex.html index 4b34d3fed..b298aa37c 100644 --- a/tests/end2end/data/downloads/mhtml/complex/complex.html +++ b/tests/end2end/data/downloads/mhtml/complex/complex.html @@ -80,7 +80,7 @@

...and how?

-

See +

See here for more information.

More useless trivia!

diff --git a/tests/end2end/data/downloads/mhtml/complex/complex.mht b/tests/end2end/data/downloads/mhtml/complex/complex.mht index 0cbcc4607..0467da22f 100644 --- a/tests/end2end/data/downloads/mhtml/complex/complex.mht +++ b/tests/end2end/data/downloads/mhtml/complex/complex.mht @@ -97,7 +97,7 @@ the

...and how?

=20

See +aster/doc/contributing.asciidoc"> here for more information.

=20

More useless trivia!

diff --git a/www/header.asciidoc b/www/header.asciidoc index b463de7d2..8d9b5ac21 100644 --- a/www/header.asciidoc +++ b/www/header.asciidoc @@ -9,10 +9,10 @@