Contribute to the documentation
From a terminal window navigate to the documentation root:
To serve a development copy run:
This command will print a bunch of debugging information, but once completed you should see:
Starting server ... Serving book on http://localhost:4040
Just open that URL in your browser and you'll be able to see the documentation.
Prepare to make changes
The documentation is stored in a
git repository together with the rest of the code,
so the process to submit a patch is the same as described here.
Let's get started by creating a new
branch to keep our changes:
repo start feature/my-amazing-doc-changes
You're now ready to start making changes!
Making changes to an existing page
To make changes to an existing page, just locate the correct
An easy way to do this is to navigate to the page you want to look at and look at the URL. A URL like
http://localhost:4040/developer/getting_the_code.htmlwill translate to a file located in
Note that the files are written in
markdown, if you are not familiar with it
please take a look at this cheatsheet.
Most IDEs and Editors have plugins to format
markdown that will give you a good preview,
but remember that you have a development server running, so you can always go back in the
browser and see how your changes look like.
So just go ahead and make the changes you want!
Adding a new page
If you want to add a new page create a new
.md file in the appropriate location.
We are trying to group together files by topic, so just try to find the most meaningful
folder for your new guide. That will make it easier for others to consume and improve it.
For this example we are going to create a new page in
and we will insert some dummy content:
touch ~/cord/docs/developer/test_page.md echo "# Test Page" > ~/cord/docs/developer/test_page.md
The last operation we need to do is to add the page to the navigation. To do that
~/cord/docs/SUMMARY.md and insert the new link, such as:
... * [Development Guide](developer/developer.md) * [Getting the Source Code](developer/getting_the_code.md) * [Modeling Services](developer/xos-intro.md) * [Developer Workflows](developer/workflows.md) * [Service Migrations](xos/dev/xosmigrate.md) * [Building Docker Images](developer/imagebuilder.md) * [GUI Development](xos-gui/developer/README.md) * [Quickstart](xos-gui/developer/quickstart.md) * [GUI Extensions](xos-gui/developer/gui_extensions.md) * [GUI Internals](xos-gui/architecture/README.md) * [Module Strucure](xos-gui/architecture/gui-modules.md) * [Data Sources](xos-gui/architecture/data-sources.md) * [Tests](xos-gui/developer/tests.md) * [Unit Tests](xos/dev/unittest.md) * [Versions and Releases](developer/versioning.md) * [Test Page](developer/test_page.md) ...
Submitting your changes for review
Regardless wether you created a new page or improved a new one the process to submit a patch is the same.
Start by verifying that your changes are passing the validation. This happens automatically on Jenkins, but it's always better to check before uploading a path, so execute:
Then check what has changed in the source tree by running
here is a typical output:
On branch feature/contribute_to_the_docs Your branch is up-to-date with 'opencord/master'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git checkout -- <file>..." to discard changes in working directory) modified: SUMMARY.md Untracked files: (use "git add <file>..." to include in what will be committed) .idea/ att-workflow-driver automation-tools cord-tester developer/contribute_to_the_docs.md exampleservice fabric fabric-crossconnect hippie-oss kubernetes-service olt-service onos-service openolt openstack rcord simpleexampleservice vrouter vtn-service xos xos-gui xos-tosca
Note that there a bunch of files not included in
git. Those files can't be added to
.gitignore as otherwise
gitbook will ignore them too, so please be careful
in including only the file you changed/created:
git add SUMMARY.md git add developer/contribute_to_the_docs.md
Then commit and upload the changes:
git commit -m "documentation changes" repo upload . -t