From: Thomas Kulik Date: Tue, 8 Jun 2021 13:06:23 +0000 (+0000) Subject: Merge "Update doc/tools" X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=dbc24685bb9abd4a4acc18af99b20d889bff9faa;hp=3353c6e1257561d79e7e0975c936ce6ffaa104fa;p=doc.git Merge "Update doc/tools" --- 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 `__. - 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 `__. + ------------------------------------------------------------------------------- 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 `__ + +Git +--- + +- `How To Install Git on Ubuntu 20.04 `__ + Python ------ @@ -606,6 +626,12 @@ Python - `Getting Started with Python in VS Code `__ - `Linux Foundation Docs Conf `__ +ReadTheDocs Sphinx Theme +------------------------ + +- `ReadTheDocs Sphinx Theme (Recommended Reading!) `__ +- `ReadTheDocs Sphinx Theme Configuration `__ + reStructuredText ---------------- @@ -614,11 +640,10 @@ reStructuredText - `reStructuredText and Sphinx Cheat Sheet II `__ - `Online reStructuredText Editor `__ -ReadTheDocs Sphinx Theme ------------------------- +Ubuntu +------ -- `ReadTheDocs Sphinx Theme (highly recommended) `__ -- `ReadTheDocs Sphinx Theme Configuration `__ +- `Virtualized Ubuntu Desktop Edition `__ Visual Studio Code (VSC) ------------------------ @@ -627,16 +652,6 @@ Visual Studio Code (VSC) - `Code Formatting with Prettier in Visual Studio Code `__ - `VSC Icons `__ -Git ---- - -- `How To Install Git on Ubuntu 20.04 `__ - -Documentation -------------- - -- `Write The Docs: Documentation Guide `__ - ------------------------------------------------------------------------------- Backlog