Commit 84b7ddb7 authored by Julien Satti's avatar Julien Satti ✨
Browse files

Deployed 0c6b6899 to develop in public with MkDocs 1.6.1 and mike 2.1.3

parent bd112c59

public/develop/contribute/documenting/index.html

+196 −17
Original line number Diff line number Diff line
@@ -598,12 +598,54 @@ 
</li>

      

        <li class="md-nav__item">

  <a href="#documentation-system-and-structure" class="md-nav__link">

  <a href="#system-and-structure" class="md-nav__link">

    <span class="md-ellipsis">

      Documentation System and Structure

      System and Structure

    </span>

  </a>

  

    <nav class="md-nav" aria-label="System and Structure">

      <ul class="md-nav__list">

        

          <li class="md-nav__item">

  <a href="#how-it-works" class="md-nav__link">

    <span class="md-ellipsis">

      How it works?

    </span>

  </a>

  

</li>

        

          <li class="md-nav__item">

  <a href="#branches" class="md-nav__link">

    <span class="md-ellipsis">

      Branches

    </span>

  </a>

  

</li>

        

          <li class="md-nav__item">

  <a href="#structure" class="md-nav__link">

    <span class="md-ellipsis">

      Structure

    </span>

  </a>

  

</li>

        

          <li class="md-nav__item">

  <a href="#main-page" class="md-nav__link">

    <span class="md-ellipsis">

      Main Page

    </span>

  </a>

  

</li>

        

      </ul>

    </nav>

  

</li>

      

        <li class="md-nav__item">
@@ -613,6 +655,30 @@ 
    </span>

  </a>

  

    <nav class="md-nav" aria-label="Getting Started">

      <ul class="md-nav__list">

        

          <li class="md-nav__item">

  <a href="#add-documentation-during-development" class="md-nav__link">

    <span class="md-ellipsis">

      Add Documentation During Development

    </span>

  </a>

  

</li>

        

          <li class="md-nav__item">

  <a href="#release-a-new-version-of-the-documentation" class="md-nav__link">

    <span class="md-ellipsis">

      Release a New Version of the Documentation

    </span>

  </a>

  

</li>

        

      </ul>

    </nav>

  

</li>

      

    </ul>
@@ -687,12 +753,54 @@ 
</li>

      

        <li class="md-nav__item">

  <a href="#documentation-system-and-structure" class="md-nav__link">

  <a href="#system-and-structure" class="md-nav__link">

    <span class="md-ellipsis">

      Documentation System and Structure

      System and Structure

    </span>

  </a>

  

    <nav class="md-nav" aria-label="System and Structure">

      <ul class="md-nav__list">

        

          <li class="md-nav__item">

  <a href="#how-it-works" class="md-nav__link">

    <span class="md-ellipsis">

      How it works?

    </span>

  </a>

  

</li>

        

          <li class="md-nav__item">

  <a href="#branches" class="md-nav__link">

    <span class="md-ellipsis">

      Branches

    </span>

  </a>

  

</li>

        

          <li class="md-nav__item">

  <a href="#structure" class="md-nav__link">

    <span class="md-ellipsis">

      Structure

    </span>

  </a>

  

</li>

        

          <li class="md-nav__item">

  <a href="#main-page" class="md-nav__link">

    <span class="md-ellipsis">

      Main Page

    </span>

  </a>

  

</li>

        

      </ul>

    </nav>

  

</li>

      

        <li class="md-nav__item">
@@ -702,6 +810,30 @@ 
    </span>

  </a>

  

    <nav class="md-nav" aria-label="Getting Started">

      <ul class="md-nav__list">

        

          <li class="md-nav__item">

  <a href="#add-documentation-during-development" class="md-nav__link">

    <span class="md-ellipsis">

      Add Documentation During Development

    </span>

  </a>

  

</li>

        

          <li class="md-nav__item">

  <a href="#release-a-new-version-of-the-documentation" class="md-nav__link">

    <span class="md-ellipsis">

      Release a New Version of the Documentation

    </span>

  </a>

  

</li>

        

      </ul>

    </nav>

  

</li>

      

    </ul>
@@ -724,20 +856,46 @@ 
<h2 id="eligibility">Eligibility</h2>

<p>Documenting OpenCAPIF is limited to active contributors. So, if you:</p>

<ol>

<li>

<p>are an active member or participant;</p>

</li>

<li>

<p>wish to contribute to it;</p>

</li>

<li>

<p>you're ready!</p>

</li>

<li>are an active member or participant;</li>

<li>wish to contribute to it;</li>

<li>you're ready!</li>

</ol>

<h2 id="documentation-system-and-structure">Documentation System and Structure</h2>

<h2 id="system-and-structure">System and Structure</h2>

<p><a href="https://www.mkdocs.org/">MkDocs</a> is a fast and simple static site generator that's geared towards building project documentation. Documentation source files are written in <code>Markdown</code>, and configured with a single <code>YAML</code> configuration file. Start by reading the <a href="https://www.mkdocs.org/getting-started/">introductory tutorial</a>, then check the <a href="https://www.mkdocs.org/user-guide/">User Guide</a> for more information.</p>

<h3 id="how-it-works">How it works?</h3>

<p>There are 2 ways to upgrade documentation published on <a href="https://ocf.etsi.org/documentation/" title="OCF Documentation">OCF Documentation</a>:

* Push any change on <strong>develop</strong> branch will force update of <strong>develop</strong> version on the <a href="https://ocf.etsi.org/documentation/" title="OCF Documentation">OCF Documentation</a> website;

* Create a tag, this will create a version with tag name on the <a href="https://ocf.etsi.org/documentation/" title="OCF Documentation">OCF Documentation</a> website.</p>

<h3 id="branches">Branches</h3>

<p>This documentation repository has 2 protected branches:</p>

<ul>

<li><strong>main</strong>: this branch will store the information stable;</li>

<li><strong>develop</strong>: any change uploaded on this branch will upgrade <strong>develop</strong> version of the documentation published on the <a href="https://ocf.etsi.org/documentation/" title="OCF Documentation">OCF Documentation</a> website.</li>

</ul>

<h3 id="structure">Structure</h3>

<p>In the <code>mkdocs.yml</code> file you will find the navigation structure of the documentation, there you can sections with sub-sections.</p>

<p><em>For example:</em></p>

<pre><code class="language-yaml">nav:

  - Overview:

      - Introduction: index.md

  - Getting Started:

      - How to Run: ./gettingstarted/howtorun.md

  - Testing:

      - Test Plan: ./testing/testplan/README.md

      - Robot Framework: ./testing/robotframework/README.md

      - Postman: ./testing/postman/README.md

  - FAQ: ./FAQ.md

</code></pre>

<p>As you can see here, we have at the time of writing this page, 5 main sections:

* Overview: here we placed high-level information like version changelog, some initial scripts, ...

* Getting Started: this section contains a simple way to start working with the project;

* Testing: detailed information of <strong>how to test</strong> OpenCAPIF, and test plan developed to ensure the code has all implemented functionality checked;

* Contribute: details about how to contribute code and docs;

* FAQ.</p>

<h3 id="main-page">Main Page</h3>

<p>The page shown first is at <strong>doc/index.md</strong>. That page should be updated with the latest changes of OpenCAPIF, also including the version.</p>

<h2 id="getting-started">Getting Started</h2>

<p>To contribute to OpenSlice's documentation, you need to follow those easy steps:</p>

<p>To contribute to OpenCAPIF's documentation, you need to follow these easy steps:</p>

<p>1) Clone the <a href="https://labs.etsi.org/rep/ocf/documentation">Documentation repository</a> with:</p>

<pre><code class="language-bash">git clone https://labs.etsi.org/rep/ocf/documentation.git

</code></pre>
@@ -745,14 +903,14 @@ 
<pre><code class="language-bash">cd ./documentation

git checkout develop

</code></pre>

<p>3) Setup a local mkdocs server, using a virtual environment:</p>

<p>3) Setup a local <code>mkdocs</code> server, using a virtual environment:</p>

<pre><code class="language-bash">python3 -m venv venv

source venv/bin/activate

python -m pip install mkdocs

python -m pip install mkdocs-material

python -m pip install mike

</code></pre>

<p>4) Wait for all downloads to finish and start the mkdocs server:</p>

<p>4) Wait for all downloads to finish and start the local <code>mkdocs</code> server:</p>

<pre><code class="language-bash">mkdocs serve

</code></pre>

<p>5) Document (and commit)! 😊</p>
@@ -760,6 +918,27 @@ python -m pip install mike 
<blockquote>

<p>The documentation website supports branches, so your accepted changes will be reflected to the <strong>develop</strong> branch which becomes the <strong>release</strong> branch after each corresponding cycle.</p>

</blockquote>

<h3 id="add-documentation-during-development">Add Documentation During Development</h3>

<p>To update the documentation during development, follow those steps:</p>

<ol>

<li>Perform the development of functionality on <code>capif</code> code repository;</li>

<li>Create an issue on <a href="https://labs.etsi.org/rep/ocf/documentation/-/issues">GitLab</a>;</li>

<li>Create a new branch with source from <strong>develop</strong>;</li>

<li>Update documentation:</li>

<li><strong><em>Remember to update index.md with new functionalities for the latest version</em></strong>;</li>

<li>New test plan is defined? <strong>Update test plan documentation</strong></li>

<li>Check if errors are being produced by <code>mkdocs</code> <a href="#getting-started">locally</a>;</li>

<li>Push changes to branch;</li>

<li>Create a merge/pull request;</li>

<li>Send the request to review to at least one TSC Member for approval.</li>

</ol>

<h3 id="release-a-new-version-of-the-documentation">Release a New Version of the Documentation</h3>

<p>When <strong>OpenCAPIF</strong> code repository is ready for a new release, we need to follow these steps (made by a <strong>TSC Member</strong>):</p>

<ol>

<li>Create a new branch with the released version, and merge it to <strong>develop</strong>;</li>

<li>Create a Merge request from <strong>develop</strong> to <strong>main</strong>;</li>

<li>When develop is merged to <strong>main</strong>, then we need to <strong>create a tag with the released version</strong>.</li>

</ol>

public/develop/search/search_index.json

+1 −1

File changed.

Preview size limit exceeded, changes collapsed.