Google Git
Sign in
apache / mynewt-site / refs/heads/asf-site / . / v1_0_0 / faq / how_to_edit_docs / index.html
blob: db93da9fbf61f28f8fa7bdcedfbc9377150646d2 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../img/favicon.ico">
<title>Edit Docs - Apache Mynewt</title>
<link href="../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
<link rel="stylesheet" href="../../css/highlight.css">
<link href="../../css/base.css" rel="stylesheet">
<link href="../../css/custom.css" rel="stylesheet">
<link href="../../css/v2.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="Edit Docs">
<div class="container">
<div class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.12.0, Apache NimBLE 1.7.0 </a> released (April 4, 2024)
</div>
</div>
</div>
</div>
<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li
class=""
>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li
class="important"
>
<a href="/quick-start/">Quick Start</a>
</li>
<li
class=""
>
<a href="/about/">About</a>
</li>
<li
class=""
>
<a href="/talks/">Talks</a>
</li>
<li
class="active"
>
<a href="/documentation/">Documentation</a>
</li>
<li
class=""
>
<a href="/download/">Download</a>
</li>
<li
class=""
>
<a href="/community/">Community</a>
</li>
<li
class=""
>
<a href="/events/">Events</a>
</li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary">
<div class="top">
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search documentation" />
</div>
</form>
</div>
</div>
<ul class="toc-nav">
<li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest">
Version: master
</option>
<option value="/v1_12_0/" >
Version: 1.12.0
</option>
<option value="/v1_11_0/" >
Version: 1.11.0
</option>
<option value="/v1_10_0/" >
Version: 1.10.0
</option>
<option value="/v1_9_0/" >
Version: 1.9.0
</option>
<option value="/v1_8_0/" >
Version: 1.8.0
</option>
<option value="/v1_7_0/" >
Version: 1.7.0
</option>
<option value="/v1_6_0/" >
Version: 1.6.0
</option>
<option value="/v1_5_0/" >
Version: 1.5.0
</option>
<option value="/v1_4_0/" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" selected="selected" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select></li>
<li ><a href="../../os/introduction/">Mynewt Documentation</a>
</li>
<li><a href="
../go_env/
">Appendix</a>
<ul>
<li >
<a href="../go_env/">Setting Up Go to Contribute to Newt and Newtmgr Tools</a>
</li>
<li >
<a href="../ide/">Using an IDE to Develop Mynewt Applications</a>
</li>
<li class="active">
<a href="./">Edit Docs</a>
</li>
<li >
<a href="../answers/">FAQ</a>
</li>
</ul>
</li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<div class="doc-header">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; <a href="faq/go_env/">Appendix</a></li>
<li>&raquo; Edit Docs</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.0.0 is not the most recent version of the Apache Mynewt
documentation. Click <a href="/latest">here</a> to read the latest
version.
</p>
</div>
<h2 id="how-to-edit-docs">How to Edit Docs</h2>
<h3 id="objective">Objective</h3>
<p>Learn the process of editing docs by adding some content to a test document.</p>
<h3 id="markdown-mkdocs-mou">Markdown, MkDocs, Mou</h3>
<p>The Mynewt documentation you see on the Apache incubator website is a bunch of HTML files generated using MkDocs which is a simple static site generation tool geared towards building project documentation. You can read about it at <a href="http://www.mkdocs.org">http://www.mkdocs.org</a>. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool (which in our case is MkDocs).</p>
<p>The HTML pages are generated periodically after changes have been reviewed and accepted into the master branch.</p>
<h3 id="access-to-the-apache-repo">Access to the Apache repo</h3>
<p>Get an account on Apache. You do not need a committer account to view the website or clone the repository but you need it to push changes to it.</p>
<p>If you are not a committer, you may follow the proposed non-committer workflow to share your work. The direct link to the proposed workflow is <a href="https://git-wip-us.apache.org/docs/workflow.html">https://git-wip-us.apache.org/docs/workflow.html</a>. You will find the steps described in more detail later in this tutorial.</p>
<h3 id="editing-an-existing-page">Editing an existing page</h3>
<ul>
<li>Create a fork on the <a href="https://github.com/apache/incubator-mynewt-site">github mirror</a>.</li>
<li>Create a new branch to work on your documentation and move to that branch.</li>
</ul>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code> $ git checkout -b &lt;your-branch-name&gt;
</code></pre></div>
<ul>
<li>Make changes directly on github.com. Generate a pull request. Alternatively, you can edit locally on your machine, push the branch (or the changes in the branch) to your fork on github.com, and then generate a pull request.</li>
</ul>
<h3 id="adding-a-new-page">Adding a new page</h3>
<p>If you create a new file somewhere in the <code>docs</code> subdirectory to add a new page, you have to add a line in the <code>mkdocs.yml</code> file at the correct level. For example, if you add a new module named "Wi-Fi" by creating a new file named <code>wifi.md</code> in the <code>network</code> directory, you have to insert the following line under <code>Networking User Guide</code> in the <code>mkdocs.yml</code> file (at the same level as the <code>docs</code> directory). In this example, a link will show up in the navigation bar on the left under "Networking User Guide" titled "Wi-Fi" and take the user to the contents of the 'wifi.md' file when the link is clicked. ** Note: The change will show up on this <a href="http://mynewt.apache.org">Mynewt site</a> only after your pull request is merged in and the updated site is generated.**</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code> - &#39;Wi-Fi&#39;: &#39;wifi.md&#39;
</code></pre></div>
<h3 id="local-preview-of-html-files">Local preview of HTML files</h3>
<p>You have the option to install MkDocs and do a local conversion yourself to preview the pages using the built-in webserver that comes with MkDocs. In order to install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have them already (usually you will).</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code> $ python --version
Python 2.7.2
$ pip --version
pip 1.5.2
$ pip install mkdocs
</code></pre></div>
<p>You will then run the built-in webserver from the root of the documentation directory using the command <code>mkdocs serve</code>. The root directory for documentation is <code>incubator-mynewt-site</code> or the directory with the <code>mkdocs.yml</code> file.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code> $ ls
docs images mkdocs.yml
$ mkdocs serve
</code></pre></div>
<p>Then go to <a href="http://127.0.0.1:8000">http://127.0.0.1:8000</a> to preview your pages and see how they will look on the website. <strong>Remember that the <a href="https://mynewt.apache.org">MyNewt website</a> itself will not be updated.</strong></p>
<p>For more information on MkDocs go to <a href="http://www.mkdocs.org">http://www.mkdocs.org</a>. </p>
<div class="row">
<ul class="nav nav-pills" style="margin-bottom: 10px">
<li>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt (incubating) is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<a href="https://www.apache.org/">
<img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
</a>
<p>
Copyright © 2015-2021 The Apache Software Foundation.<br>
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt
project logo are either registered trademarks or trademarks of the Apache
Software Foundation in the United States and other countries.
</small>
</p>
<a href="">
<img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
<a href="https://www.apache.org/licenses/">
<button class="button-footer-asf">
License
</button>
</a>
<a href="https://www.apache.org/foundation/sponsorship.html">
<button class="button-footer-asf">
Sponsorship
</button>
</a>
<a href="https://www.apache.org/foundation/thanks.html">
<button class="button-footer-asf">
Thanks
</button>
</a>
<a href="https://www.apache.org/security/">
<button class="button-footer-asf">
Security
</button>
</a>
<a href="https://apache.org/events/current-event">
<button class="button-footer-asf">
ASF Events
</button>
</a>
</footer>
</div>
</div>
</div>
<script src="../../js/jquery-1.10.2.min.js"></script>
<script src="../../js/bootstrap-3.0.3.min.js"></script>
<script src="../../js/highlight.pack.js"></script>
<script src="../../js/base.js"></script>
<script src="../../js/custom.js"></script>
<script src="search/main.js"></script>
</body>
</html>