This commit is contained in:
commit
c72f103716
|
@ -1,9 +1,12 @@
|
||||||
image: alpine
|
image: alpine
|
||||||
|
|
||||||
|
before_script:
|
||||||
|
- apk --no-cache add make py3-setuptools python3-dev
|
||||||
|
- python3 -m pip install sphinx sphinx_rtd_theme
|
||||||
|
|
||||||
pages:
|
pages:
|
||||||
|
stage: deploy
|
||||||
script:
|
script:
|
||||||
- apk --no-cache add make py3-setuptools python3-dev
|
|
||||||
- python3 -m pip install sphinx sphinx_rtd_theme
|
|
||||||
- cd manual
|
- cd manual
|
||||||
- make html
|
- make html
|
||||||
- mv build/html/ ../public/
|
- mv build/html/ ../public/
|
||||||
|
@ -12,3 +15,15 @@ pages:
|
||||||
- public
|
- public
|
||||||
only:
|
only:
|
||||||
- master
|
- master
|
||||||
|
|
||||||
|
test:
|
||||||
|
stage: test
|
||||||
|
script:
|
||||||
|
- cd manual
|
||||||
|
- make html
|
||||||
|
- mv build/html/ ../test/
|
||||||
|
artifacts:
|
||||||
|
paths:
|
||||||
|
- test
|
||||||
|
except:
|
||||||
|
- master
|
||||||
|
|
|
@ -0,0 +1,71 @@
|
||||||
|
OpenLP Documentation
|
||||||
|
====================
|
||||||
|
This repository holds the OpenLP manual and some other documentation.
|
||||||
|
|
||||||
|
Getting Started
|
||||||
|
---------------
|
||||||
|
To get up and running with the documentation, you'll need to install `Sphinx <https://www.sphinx-doc.org>`_
|
||||||
|
and the `Read The Docs theme <https://sphinx-rtd-theme.readthedocs.io>`_.
|
||||||
|
|
||||||
|
Linux
|
||||||
|
~~~~~
|
||||||
|
If you're using Linux, you'll want to check your package manager for those packages.
|
||||||
|
|
||||||
|
Ubuntu/Debian::
|
||||||
|
|
||||||
|
$ sudo apt install python3-sphinx python3-sphinx-rtd-theme
|
||||||
|
|
||||||
|
Fedora::
|
||||||
|
|
||||||
|
$ sudo dnf install python3-sphinx python3-sphinx_rtd_theme
|
||||||
|
|
||||||
|
macOS
|
||||||
|
~~~~~
|
||||||
|
On macOS you can install Sphinx via MacPorts or Homebrew.
|
||||||
|
|
||||||
|
MacPorts::
|
||||||
|
|
||||||
|
$ sudo port install py37-sphinx py37-sphinx_rtd_theme
|
||||||
|
|
||||||
|
Homebrew::
|
||||||
|
|
||||||
|
$ sudo brew install sphinx-doc
|
||||||
|
|
||||||
|
Homebrew doesn't have the Read The Docs theme, so you'll need to install it via pip::
|
||||||
|
|
||||||
|
$ sudo pip install sphinx_rtd_theme
|
||||||
|
|
||||||
|
Windows
|
||||||
|
~~~~~~~
|
||||||
|
On Windows you'll need to use ``pip`` to install Sphinx and the Read The Docs theme::
|
||||||
|
|
||||||
|
$ pip install sphinx sphinx_rtd_theme
|
||||||
|
|
||||||
|
Editing the Documentation
|
||||||
|
-------------------------
|
||||||
|
The documentation is written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_. If
|
||||||
|
you haven't ever used reStructuredText before, take a look at the
|
||||||
|
`reStructuredText primer <http://www.sphinx-doc.org/en/stable/rest.html>`_ for a good introduction
|
||||||
|
to the format.
|
||||||
|
|
||||||
|
reStructuredText is a plain-text format, so any text editor will work. Popular editors are
|
||||||
|
`vim <https://www.vim.org/>`_, `Atom <https://atom.io/>`_,
|
||||||
|
`Visual Studio Code <https://code.visualstudio.com/>`_ (Linux, macOS, Windows),
|
||||||
|
`Notepad++ <https://notepad-plus-plus.org/>`_ (Windows).
|
||||||
|
|
||||||
|
Building the Documentation
|
||||||
|
--------------------------
|
||||||
|
Now that you have the dependencies installed and you've edited some pages, you'll want to build the
|
||||||
|
documentation. Let's start with the manual. Go into the ``manual`` directory, and then run
|
||||||
|
``make html``::
|
||||||
|
|
||||||
|
$ cd manual
|
||||||
|
$ make html
|
||||||
|
|
||||||
|
This will run Sphinx on the documentation and build the HTML in the ``build/html`` directory. To
|
||||||
|
view the documentation, let's run Python's built-in web server on that directory::
|
||||||
|
|
||||||
|
$ cd build/html
|
||||||
|
$ python3 -m http.server
|
||||||
|
|
||||||
|
Now open your browser to `http://localhost:8000/ <http://localhost:8000/>`_ and you should see the OpenLP manual.
|
Loading…
Reference in New Issue