summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst99
1 files changed, 57 insertions, 42 deletions
diff --git a/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
index be2d29072..bdbc84383 100644
--- a/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
+++ b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
@@ -42,7 +42,7 @@ Release Relevance
8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
Last Review/Update
- none
+ 06/02/2021
Initial Release
05/12/2021
@@ -59,14 +59,8 @@ Author (Company)
Introduction
============
-Formal ONAP documentation uses the reStructuredText markup language and the
-files have an ``.rst`` extension. They are part of almost every ONAP project
-and can be found in the ``docs`` directory. The files are automatically
-processed and you find the final ONAP documentation build hosted on
-`ReadTheDocs <https://docs.onap.org>`__.
-
This guide provides a detailed description to set up a system suitable to
-create, check and preview documentation locally. The targeted readership is
+create, check and preview documentation locally. The targeted readership are
beginners and people interested in creating documentation.
The guide describes the setup of a development system from scratch using the
@@ -74,6 +68,12 @@ Ubuntu Desktop version installed in a virtual machine. It includes all required
steps and also some optional ones that may ease your daily work with this
development system. Feel free to adapt it to your needs.
+In general, formal ONAP documentation uses the reStructuredText markup language
+and the files have an ``.rst`` extension. They are part of almost every ONAP
+project and can be found in the ``docs`` directory. The files are automatically
+processed and you find the final ONAP documentation build hosted on
+`ReadTheDocs <https://docs.onap.org>`__.
+
-------------------------------------------------------------------------------
VM Configuration
@@ -296,6 +296,7 @@ your terminal has changed. Now it starts with ``(onapdocs)``.
pip3 install sphinxcontrib-swaggerdoc
pip3 install sphinxcontrib-plantuml
pip3 install lfdocs-conf
+ pip3 install pylint
which sphinx-build
@@ -431,17 +432,17 @@ Press :guilabel:`Install` if you have found the required extension.
Please install ...
-+--------------------+-----------------------------------------+
-| Python | ms-python.python |
-+--------------------+-----------------------------------------+
-| reStructuredText | lextudio.restructuredtext |
-+--------------------+-----------------------------------------+
-| Code Spell Checker | streetsidesoftware.code-spell-checker |
-+--------------------+-----------------------------------------+
-| Prettier | esbenp.prettier-vscode |
-+--------------------+-----------------------------------------+
-| GitLens | eamodio.gitlens |
-+--------------------+-----------------------------------------+
++-----------------------+-----------------------------------------+
+| Python | ms-python.python |
++-----------------------+-----------------------------------------+
+| reStructuredText | lextudio.restructuredtext |
++-----------------------+-----------------------------------------+
+| Code Spell Checker | streetsidesoftware.code-spell-checker |
++-----------------------+-----------------------------------------+
+| Prettier | esbenp.prettier-vscode |
++-----------------------+-----------------------------------------+
+| GitLens | eamodio.gitlens |
++-----------------------+-----------------------------------------+
Configure reStructuredText extension
------------------------------------
@@ -543,8 +544,8 @@ your system first.
Optional VSC Configuration
==========================
-Ruler
------
+Add Ruler
+---------
To add a ruler that indicates the line end at 79 characters, open
:guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
@@ -558,6 +559,15 @@ the value ``79``. The result should look like this:
79
]
+Disable Synchronized Scrolling of Editor and Preview
+----------------------------------------------------
+
+To disable the synchronized scrolling of editor and preview, open
+:guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
+search for ``Restructuredtext › Preview: Scroll``. Then uncheck
+:guilabel:`Restructuredtext › Preview: Scroll Editor With Preview` and
+:guilabel:`Restructuredtext › Preview: Scroll Preview With Editor`
+
-------------------------------------------------------------------------------
Miscellaneous
@@ -572,13 +582,13 @@ Firefox Add-ons
Open :guilabel:`Add-Ons and Themes`, then search and install the following
add-ons:
-+----------------------------+-------------------------------+
-| I don't care about cookies | Get rid of cookie warnings. |
-+----------------------------+-------------------------------+
-| UBlock Origin | A wide-spectrum blocker. |
-+----------------------------+-------------------------------+
-| LastPass Password Manager | Used in the Linux Foundation. |
-+----------------------------+-------------------------------+
++------------------------------+-------------------------------+
+| I don't care about cookies | Get rid of cookie warnings. |
++------------------------------+-------------------------------+
+| UBlock Origin | A wide-spectrum blocker. |
++------------------------------+-------------------------------+
+| LastPass Password Manager | Used in the Linux Foundation. |
++------------------------------+-------------------------------+
ReText Editor
-------------
@@ -597,6 +607,16 @@ Helpful Resources
This is a collection of helpful resources if you want to extend and deepen your
knowledge.
+Documentation
+-------------
+
+- `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
+
+Git
+---
+
+- `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
+
Python
------
@@ -606,6 +626,12 @@ Python
- `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`__
- `Linux Foundation Docs Conf <https://pypi.org/project/lfdocs-conf/>`__
+ReadTheDocs Sphinx Theme
+------------------------
+
+- `ReadTheDocs Sphinx Theme (Recommended Reading!) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
+- `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
+
reStructuredText
----------------
@@ -614,11 +640,10 @@ reStructuredText
- `reStructuredText and Sphinx Cheat Sheet II <https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html>`__
- `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
-ReadTheDocs Sphinx Theme
-------------------------
+Ubuntu
+------
-- `ReadTheDocs Sphinx Theme (highly recommended) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
-- `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
+- `Virtualized Ubuntu Desktop Edition <https://linuxconfig.org/ubuntu-20-04-system-requirements>`__
Visual Studio Code (VSC)
------------------------
@@ -627,16 +652,6 @@ Visual Studio Code (VSC)
- `Code Formatting with Prettier in Visual Studio Code <https://www.digitalocean.com/community/tutorials/code-formatting-with-prettier-in-visual-studio-code>`__
- `VSC Icons <https://github.com/microsoft/vscode-icons>`__
-Git
----
-
-- `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
-
-Documentation
--------------
-
-- `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
-
-------------------------------------------------------------------------------
Backlog