github.com/cilium/cilium@v1.16.2/Documentation/contributing/docs/docstest.rst (about)

     1  .. only:: not (epub or latex or html)
     2    
     3      WARNING: You are looking at unreleased Cilium documentation.
     4      Please use the official rendered version released here:
     5      https://docs.cilium.io
     6  
     7  .. _testing-documentation:
     8  
     9  Documentation testing
    10  =====================
    11  
    12  First, start a local document server that automatically refreshes when you save files for
    13  real-time preview. It relies on the ``cilium/docs-builder`` Docker container.
    14  
    15  Set up your development environment
    16  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    17  
    18  To run Cilium's documentation locally, you need to install `docker engine <https://docs.docker.com/engine/install/>`_ and also the ``make`` package.
    19  To verify that ``make`` and ``docker`` is installed, run the command ``make --version`` and ``docker --version`` in your terminal.
    20  
    21  .. code-block:: shell-session
    22  
    23      $ docker --version
    24      Docker version 20.10.22, build 3a2c30b
    25      $ make --version
    26      GNU Make 4.2.1
    27  
    28  For Windows
    29  ~~~~~~~~~~~
    30  
    31  .. Note::
    32  
    33      The preferred method is to upgrade to Windows 10 version 1903 Build 18362 or higher, you can upgrade to Windows Subsystem for Linux ``WSL2`` and run ``make`` in Linux.
    34  
    35  #. Verify you have access to the ``make`` command in your ``WSL2`` terminal.
    36  #. Download and install docker desktop.
    37  #. Set up docker to use `WSL2 <https://docs.docker.com/desktop/windows/wsl/>`_ as backend.
    38  #. Start docker desktop.
    39  
    40  Preview documentation locally
    41  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    42  
    43  Navigate to the root of the folder where you cloned the project, then run the code below in your terminal:
    44  
    45  .. code-block:: shell-session
    46  
    47      $ make render-docs
    48  
    49  This will build a docker image and start a docker container. Preview the documentation at http://localhost:9081/ as you make changes. After making changes to
    50  Cilium documentation you should check that you did not introduce any new warnings or errors, and also
    51  check that your changes look as you intended one last time before opening a pull request. To do this
    52  you can build the docs:
    53  
    54  .. code-block:: shell-session
    55  
    56      $ make test-docs
    57  
    58  .. note::
    59  
    60     By default, ``render-docs`` generates a preview with instructions to install
    61     Cilium from the latest version on GitHub (i.e. from the HEAD of the main branch that has
    62     not been released) regardless of which Cilium branch you are in. You can target a specific
    63     branch by specifying ``READTHEDOCS_VERSION`` environment variable:
    64  
    65     .. code-block:: shell-session
    66  
    67        READTHEDOCS_VERSION=v1.7 make render-docs
    68  
    69  Submit local changes on GitHub (Pull Request)
    70  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    71  
    72  See the :ref:`submit a pull request <submit_pr>` section of the contributing guide.