“Open source is this magical thing right? You release code, and the code gnomes come and make it better for you.
Not quite. There are lots of ways that open source is amazing, but it doesn’t exist outside the laws of physics. You have to put work in, to get work out.
You only get contributions after you have put in a lot of work. You only get contributions after you have users. You only get contributions after you have documentation.”
From @ericholscher guide to writing docs
Table of contents¶
Jina documentation adheres to the following hierarchical structure. Each Jina product has its own section, containing three subsections below.
|Overview||A high level conceptual overview of the product. Introducing terms and broad architectural concepts. Content here should apply to all Jina users. For example, all users should understand what a Pod is, but only some users need to understand deployment on a GPU.|
|Developer Guides||Are technical how-to guides/tutorials which describe product features or implementations. Assumes basic knowledge of the product and related terms.|
|API References||Are detailed descriptions of the product API. Possibility auto-generated from docstrings or open API references. Describes how the methods work and which parameters can be used.|
How to add pages¶
For getting started pages and developer guides:
A page can be written in Markdown or reStructuredText format.
Use a template from the page_templates folder.
Using Git, clone the repo:
git clone https://github.com/jina-ai/docs.
Create a git new branch:
git checkout -b fix_pods.
Your commit messages should following the standard Jina format seen here.
Add your file to the chapters folder.
Add your file to a table of contents.
Push your branch and create a pull request.
Add at least two people to your pull request review. One product manager and one developer.
You can preview how the docs website will look with your changes. Inside your pull request, navigate to checks and click ‘preview with netlify’.
After the pull request is merged, the website will automatically update.
Build docs locally¶
#Clone the code. git clone https://github.com/jina-ai/docs.git #Install dependencies. pip install -r requirements.txt # Clean & build docs locally make dirhtml # Serve the docs website with Python 3 python -m http.server 8080 -d _build/dirhtml