diff --git a/source/contributing/github.rst b/source/contributing/github.rst deleted file mode 100644 index d3c8bdf2..00000000 --- a/source/contributing/github.rst +++ /dev/null @@ -1,164 +0,0 @@ - -.. meta:: - :description: This document will help guide you through the contribution process for the NGINX Wiki. - -Submitting Contributions -======================== - -The NGINX Wiki is automatically generated from `reStructuredText files `_ using `Sphinx Documentation Generator `_. The source files are `stored in GitHub `_ and are open to contributions via pull requests. This document will help guide you through this process. - -Editing on GitHub ------------------ - -Whilst viewing wiki you will find "Edit on GitHub" links in the sidebar on every page. Using this you can edit page content and submitting your edits will generate a pull request. This is a relatively simple way to make quick edits. - -Editing on your local computer ------------------------------- - -These instructions are for Linux and Mac users, and assume you have a GitHub account and the ``git`` command-line tool is installed. - -You also need *python-sphinx* installed; some Linux distributions have this in their repositories, while for others you can install it using ``pip``: - -.. code-block:: bash - - $ sudo pip install -r requirements.txt - -GitHub's Two-Factor Authentication ----------------------------------- - -If you use GitHub's `two-factor authentication `_ (highly recommended), you can use an access token instead of a password when accessing GitHub with the instructions outlined in this document. This can be obtained from your `application settings page `_. - -Alternatively, you can use SSH to access GitHub. Simply go to your `SSH keys page `_, add your key, and change the URLs in this document from ``https://github.com//nginx-wiki.git`` to ``git@github.com:/nginx-wiki.git``. - -Forking -------- - -You need to create a *fork* of the source so that you have a working area for it. To do this go to the `NGINX Wiki GitHub page `_, sign in, and click the *Fork* button near the top. Once you have forked you can get a local copy of this fork to work on. To do this, run the following command in your console (where <*user*> is your username): - -.. code-block:: bash - - $ git clone https://github.com//nginx-wiki.git - -You then need to associate your local clone with the upstream repository: - -.. code-block:: bash - - $ cd nginx-wiki - $ git remote add upstream https://github.com/nginxinc/nginx-wiki.git - -Branch ------- - -Every new batch of additions/edits you want to merge into the Wiki needs its own branch. Before creating a new branch, first make sure your local copy is up to date: - -.. code-block:: bash - - $ git checkout master - $ git pull --ff-only upstream master - $ git push - -You can then create a new branch based on the master (replacing <*branch-name*> with the name you choose for the branch): - -.. code-block:: bash - - $ git checkout -b - -Hack on the Wiki! ------------------ - -Hack away on the changes you wish to make. See :doc:`writing_docs` for more information. - -Test ----- - -Once your edits are ready to test, run these commands to check that they build correctly: - -.. code-block:: bash - - $ make dirhtml - $ make linkcheck - -If either command generates an error, your edits probably need fixing. - -If you've recently run ``make linkcheck`` and many permanent redirects were found, you can automatically replace them all by running: - -.. code-block:: bash - - $ make linkfix - -This script is just a quick hack for the lazy, so make sure to check that it didn't break anything syntactically before you commit. - -One way to preview the output is to use NGINX. The build system can already setup NGINX for you if you have it installed: - -.. code-block:: bash - - $ make serve - -Or if you have NGINX in a non-standard path (for example ``/opt/nginx/``) you can point to the path of the NGINX binary with: - -.. code-block:: bash - - $ NGINX_PATH=/opt/nginx/sbin make serve - -You can then use your web browser to go to ``http://localhost:8080/`` and view the result. - -When you are done, **CTRL-C** will exit NGINX. - -Commit and Push ---------------- - -When you are ready to submit your changes, you need to commit them in your cloned repository and then push them up to GitHub. - -If you have never pushed code up to GitHub before, run these commands to register with ``git``: - -.. code-block:: bash - - $ git config --global user.name "Real Name" - $ git config --global user.email "me@me.com" - -Use ``git add`` to add any new files to the respository, and then commit: - -.. code-block:: bash - - $ git commit -a - -Your default text editor pops up. Enter a commit message above the comments. The first (subject) line should describe the purpose of the commit in no more than 50 characters. The second line should be blank. The third line onwards can contain details, with no more than 72 characters per line. - -If your commit fixes an issue, the first line might be something like this example for issue #45:: - - Fixes nginxinc/nginx-wiki#45 - -Once all your commits are done, you might need to do a quick rebase to make sure your changes will merge correctly into the master branch: - -.. code-block:: bash - - $ git fetch upstream - $ git rebase -i upstream/master - -Your editor should pop up again with a commit-style message that has *pick* as the first word. Save the message and the rebase will complete. If the rebase tells you there is a conflict, you will need to locate the problem using ``git diff``, fix it, and run these commands: - -.. code-block:: bash - - $ git add - $ git rebase --continue - -If things look like they are going wrong, you can undo the rebase using the following command and then get in touch with the NGINX community team for help: - -.. code-block:: bash - - $ git rebase --abort - -You should now be ready to push up to GitHub: - -.. code-block:: bash - - $ git push --set-upstream origin - -Pull Request ------------- - -When you go to your repository on GitHub's website, you will see an option to file a *Pull Request*. Use this to submit a pull request upstream for your branch. You are welcome to make multiple commits in a branch before submitting the pull request. - -.. todo: - - Travis CI will automatically test your branch and report back on the pull request; this typically takes up to 5 minutes. If there is a failure, you can commit more changes to correct the problem. When you push them up, Travis will automatically test them as part of the pull request. Your pull request will then be reviewed by a human, and merged if all is good. Feedback for you will be left on the pull request. diff --git a/source/contributing/index.rst b/source/contributing/index.rst deleted file mode 100644 index 276b109c..00000000 --- a/source/contributing/index.rst +++ /dev/null @@ -1,23 +0,0 @@ - -.. meta:: - :description: How to contribute to the NGINX codebase and to the NGINX wiki. - -Contributing to NGINX -===================== - - -A detailed breakdown of how to contribute code changes to NGINX can be found in the `NGINX documentation `_. - - -Contributing to the Wiki ------------------------- - -.. toctree:: - :maxdepth: 2 - - writing_docs - markdown - github - translating_docs - -.. todo: contributing to NGINX codebase diff --git a/source/contributing/markdown.rst b/source/contributing/markdown.rst deleted file mode 100644 index 00132a9b..00000000 --- a/source/contributing/markdown.rst +++ /dev/null @@ -1,24 +0,0 @@ - -.. meta:: - :description: Learn how to create documentation in Markdown when contributing to the NGINX Community Wiki. - -Docs in Markdown -================ - -For those who are not comfortable with writing documentation in reStructuredText form the wiki also supports documentation written in Markdown (GitHub flavoured). - -Ideally we would prefer this entire documentation to be in reStructuredText form, but understand that this could introduce a learning curve for some people. - -Creating new files ------------------- - -To create a new Markdown document simply create a file in the relevant directory with the ``.md`` extension. Sphinx will automatically understand that this is a Markdown document and render it appropriately. - -Caveats -------- - -Markdown is not modular so does not support a lot of the Sphinx reStructuredText directives and roles. Internal linking should be done using a relative path and things such as the ``:github:`` role has no equivalent in Markdown. - -Additional for new documents you will still need to edit the relevant ``index.rst`` file to add the Markdown document to the ``tocree``. Markdown does not support toctrees itself. - -Code syntax highlighting is supported and parsed using `Pygments `_, so a compatible language name should be used where appropriate. diff --git a/source/contributing/translating_docs.rst b/source/contributing/translating_docs.rst deleted file mode 100644 index fa7c2cba..00000000 --- a/source/contributing/translating_docs.rst +++ /dev/null @@ -1,48 +0,0 @@ - -.. meta:: - :description: How to translate documentation with Sphinx. Make sure to do this whenever contributing to the NGINX Wiki. - -Translating Docs -================ - -This document uses translation into Russian as an example. For other languages, replace ``ru`` with the appropriate language code. - -Setting Up the Translation Environment --------------------------------------- - -In addition to the standard ``python-sphinx`` tool, you need the ``sphinx-intl`` tool to help build the files required for translations. Run this command to install it: - -.. code-block:: bash - - $ sudo pip install sphinx-intl - -The translatable messages are then extracted using ``gettext``: - -.. code-block:: bash - - $ make gettext - -These should be used to update the locale files: - -.. code-block:: bash - - $ sphinx-intl update -p build/locale -c source/conf.py -l ru - -Translation Files ------------------ - -Once you have updated them as above, you can find the translation source files in ``source/locale/ru/LC_MESSAGES``. In each file with a ``.po`` extension are entries called ``msgid`` and ``msgstr``. ``msgid`` contains the English and ``msgstr`` is where to put the translation. If more context is needed, each entry will state the source file and line it came from. - -The ``.po`` files should be added to GitHub when committing so the translations are stored with the source. - -Testing Translations --------------------- - -Translated versions of the Wiki are built using: - -.. code-block:: bash - - $ sphinx-intl build -c source/conf.py - $ make -e SPHINXOPTS="-D language='ru'" html - -The translated output is written to ``build/html``. diff --git a/source/contributing/writing_docs.rst b/source/contributing/writing_docs.rst deleted file mode 100644 index 9b8ff5db..00000000 --- a/source/contributing/writing_docs.rst +++ /dev/null @@ -1,360 +0,0 @@ - -.. meta:: - :description: How to use reStructuredText to write documentation for the NGINX Wiki. - -Writing Documentation -===================== - -Adding new documentation ------------------------- - -If any new documentation files are added the need to be added to the *toctree* for that section. This is usually found in the ``index.rst`` file for the directory you need to add your documentation to. For example in the ``community/`` directory the ``index.rst`` file contains a toctree similar to this: - -.. code-block: rst - - .. toctree:: - - github - writing_docs - -Each one are implied to have a ``.rst`` extension. Each file will compile to a seperate HTML file when built with Sphinx. - -Adding a module document -^^^^^^^^^^^^^^^^^^^^^^^^ - -In addition to adding to the toctree, modules should be added to the big table in ``modules/index.rst``. This has three columns, the module language should use the ``:doc:`` directive to point to a ``.rst`` file for the documentation. The description should be a summary of a few words. The repository should use the :rst:role:`github` or :rst:role:`bitbucket` directive if possible, or should be a link to the repository if something else was used. - -.. todo:: - - document the :doc: directive and link to them in the paragraph above - -Please keep the modules in alphabetical order, this makes it easier for others to find them. - -reStructuredText Basics ------------------------ - -These are the basics for writing reStructuredText files. For more imformation we highly recommend looking at `Sphinx's own documentation `_ and `Quick reStructuredText `_. For a more detailed view what is possible, take a look at the `reStructuredText specification `_. - -Like Python, blocks of content are typically nested using whitespace indentation. For example: - -.. code-block:: rst - - .. note:: - - This is a note! - It is multi-line! - -.. note:: - - This is a note! - It is multi-line - -Inline Markup -^^^^^^^^^^^^^ - -There are various inline markups you can use for basic text formatting. For example: - -.. code-block:: rst - - * *emphasis* - * **bold** - * ``literal`` - * :sub:`subscript` - * :sup:`superscript` - -* *emphasis* -* **bold** -* ``literal`` -* :sub:`subscript` -* :sup:`superscript` - -Bullets and Lists -^^^^^^^^^^^^^^^^^ - -Bullets and ordered lists are very simple. - -.. code-block:: rst - - * bullet points are asterisks - - * and can be nested - * but need a blank line between parent and children - - * and another blank line to continue the parent list - -* bullet points are asterisks - - * and can be nested - * but need a blank line between parent and children - -* and another blank line to continue the parent list - -.. code-block:: rst - - #. An auto-generated numbered list - - #. It too can be nested - - #. And continue with the parent - - 1. Fixed numbered lists - 2. Are also possible - -#. An auto-generated numbered list - - #. It too can be nested - -#. And continue with the parent - -1. Fixed numbered lists -2. Are also possible - -Links -^^^^^ - -There are internal links as well as external links that are possible. - -.. code-block:: rst - - .. _reference-location: - - `NGINX Website `_ - - A link to another document: :doc:`index` - - And a link to an :ref:`abritrary reference ` - -.. _reference-location: - -`NGINX Website `_ - -A link to another document: :doc:`index` - -And a link to an :ref:`abritrary reference ` - -Headings -^^^^^^^^ - -Headings are signified by using characters on the line below to underline them. Different styles signify level. Headings are automatically used to build the table of contents for the wiki: - -.. code-block:: rst - - Heading - ======= - - SubHeading - ---------- - - More depth - ^^^^^^^^^^ - -Tables -^^^^^^ - -There are two ways to create tables, Grid Tables and Simple Tables. - -Grid Tables use ASCII art to design the table. An example is as follows: - -.. code-block:: rst - - +-----------+----------+----------+ - | Column 1 | Column 2 | Column 3 | - | Multiline | | | - +===========+==========+==========+ - | item 1 | stuff | nonsense | - +-----------+----------+----------+ - | item 2 | horizontal span | - +-----------+----------+----------+ - | item 3 | vertical | is | - +-----------+ span | possible | - | item 4 | | too. | - +-----------+----------+----------+ - -+-----------+----------+----------+ -| Column 1 | Column 2 | Column 3 | -| Multiline | | | -+===========+==========+==========+ -| item 1 | stuff | nonsense | -+-----------+----------+----------+ -| item 2 | horizontal span | -+-----------+----------+----------+ -| item 3 | vertical | is | -+-----------+ span | possible | -| item 4 | | too. | -+-----------+----------+----------+ - -Simple tables on the other hand are less flexible but are easier to create: - -.. code-block:: rst - - ======== ======== ======== - Column 1 Column 2 Column 3 - ======== ======== ======== - item a item b item c - item d item e item f - ======== ======== ======== - -======== ======== ======== -Column 1 Column 2 Column 3 -======== ======== ======== -item a item b item c -item d item e item f -======== ======== ======== - -Syntax Highlighting -^^^^^^^^^^^^^^^^^^^ - -Sphinx can highlight the syntax of code blocks. For example: - -.. code-block:: rst - - .. code-block:: c - - #include - - int main(void) - { - printf("Hello World!"); - return 0; - } - - -.. code-block:: c - - #include - - int main(void) - { - printf("Hello World!"); - return 0; - } - -There is also syntax highlighting for NGINX configuration files, here is an example of this with line numbers: - -.. code-block:: rst - - .. code-block:: nginx - :linenos: - - server { - listen 80; - server_name domain.com *.domain.com; - return 301 $scheme://www.domain.com$request_uri; - } - - server { - listen 80; - server_name www.domain.com; - - index index.html; - root /home/domain.com; - } - -.. code-block:: nginx - :linenos: - - server { - listen 80; - server_name domain.com *.domain.com; - return 301 $scheme://www.domain.com$request_uri; - } - - server { - listen 80; - server_name www.domain.com; - - index index.html; - root /home/domain.com; - } - -.. seealso:: - - `Pygments Demo `_ - A demo of the available syntax highlighting types. - -Footnotes -^^^^^^^^^ - -Footnotes in their most simple form can be generated using ``[1]_`` in the text -and then a section of the bottom of the page as follows [1]_: - -.. code-block:: rest - - .. rubric:: Footnotes - - .. [1] Like this - -Which generates: - -.. rubric:: Footnotes - -.. [1] Like this - - -Notes, Warnings, Todo and See Also -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Notes, warnings and todos all take similar forms. The wiki is configured to hide *todo* whilst rendering: - -.. code-block:: rest - - .. note:: - This is a note - - .. warning:: - This is a warning - - .. todo:: - This is a todo - - .. seealso:: - This is a See Also - -Which generates: - -.. note:: - This is a note - -.. warning:: - This is a warning - -.. todo:: - This is a todo - -.. seealso:: - This is a See Also - - -NGINX Wiki specific roles -------------------------- - -A few extra roles have been added to assist with creating documentation for this wiki. - -.. rst:role:: icon - - The icon role lets you use `Font Awesome `_ icons in text. Simply use as described in the Font Awesome documentation but without the *fa* prefix and the options comma separated. For example: - - .. code-block:: rst - - A globe example: :icon:`globe` - - A globe example: :icon:`globe` - -.. rst:role:: github - - This creates a GitHub icon with link based on a GitHub path. For example: - - .. code-block:: rst - - :github:`nginxinc/nginx-wiki` - - :github:`nginxinc/nginx-wiki` - -.. rst:role:: bitbucket - - This creates a Bitbucket icon with link based on a Bitbucket path. For example: - - .. code-block:: rst - - :bitbucket:`nginx-goodies/nginx-sticky-module-ng` - - :bitbucket:`nginx-goodies/nginx-sticky-module-ng`