From 2e573cc17114491ab5637c2026c0915abacd57b8 Mon Sep 17 00:00:00 2001 From: tsunekoh Date: Sun, 16 Aug 2020 14:48:13 +0900 Subject: [PATCH] Explain how to build Cutter docs (#2380) --- docs/source/contributing.rst | 4 +- docs/source/contributing/docs.rst | 8 ++++ .../contributing/docs/building-docs.rst | 37 +++++++++++++++++++ .../contributing/docs/getting-started.rst | 3 +- 4 files changed, 48 insertions(+), 4 deletions(-) create mode 100644 docs/source/contributing/docs.rst create mode 100644 docs/source/contributing/docs/building-docs.rst diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index af589b8d..52c0564c 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -24,6 +24,6 @@ So you like Cutter and want to get involved? Great! This part of the documentati :titlesonly: contributing/code - Contributing Documentation + contributing/docs contributing/translations/getting-started - contributing/plugins/getting-started \ No newline at end of file + contributing/plugins/getting-started diff --git a/docs/source/contributing/docs.rst b/docs/source/contributing/docs.rst new file mode 100644 index 00000000..374e879f --- /dev/null +++ b/docs/source/contributing/docs.rst @@ -0,0 +1,8 @@ +Contributing Documentation +========================== + +.. toctree:: + :maxdepth: 2 + + Getting Started + docs/building-docs diff --git a/docs/source/contributing/docs/building-docs.rst b/docs/source/contributing/docs/building-docs.rst new file mode 100644 index 00000000..4ff22d10 --- /dev/null +++ b/docs/source/contributing/docs/building-docs.rst @@ -0,0 +1,37 @@ +Building docs +======================= + +This page explains the steps that are needed to build Cutter's documentation. + +Requirements +------------ + +You will need: + +* doxygen +* python3 +* pip3 + + * sphinx + * breathe + * recommonmark + +On Debian-based Linux distributions, the packages above can be installed with the following command. + +.. code:: sh + + sudo apt install make doxygen python3-pip doxygen + sudo pip3 install sphinx breathe recommonmark + +Then, you can build the documentation with the following commands: + +.. code:: sh + + cd cutter/docs/ + make html + +.. tip:: + + If you do not need API documentation, type ``make quick`` instead of ``make html``. + +You can find the generated html files at ``cutter/docs/build``. Open ``cutter/docs/build/html/index.html`` with your browser to visit the index file of your local copy of the documentation. diff --git a/docs/source/contributing/docs/getting-started.rst b/docs/source/contributing/docs/getting-started.rst index 7cf17ed6..230d4369 100644 --- a/docs/source/contributing/docs/getting-started.rst +++ b/docs/source/contributing/docs/getting-started.rst @@ -16,8 +16,7 @@ How can you help? The following sections suggest ways you can contribute to Cutter's documentation. The list isn't complete as the possibilities are limitless. -The source for this documentation is available in the `docs directory `_ on Cutter's repository. When the docs are updated, they are generated and pushed directly to the website at . The source for the website and blog are available on the `cutter.re's repository `_ and are served from the ``gh-pages`` branch. - +The source for this documentation is available in the `docs directory `_ on Cutter's repository. This source can be generated according to the steps described in the :ref:`building docs page`. When the docs are updated, they are generated and pushed directly to the website at . The source for the website and blog are available on the `cutter.re's repository `_ and are served from the ``gh-pages`` branch. .. tip:: Document what you wished to see. If you are a user of Cutter, try to think what things you would want to see documented when you started using the project. Sometimes, the best contributions are coming from your own needs.