Jina Documentation
“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
- Hierarchical structure
- Missing content
- How to add pages
- Updating Docstrings
- Jina style guide
- Technical aspects of the the doc site
Hierarchical structure
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. |
Missing content
If you find a gap in our documentation, please submit a GitHub issue here.
Documentation process
All documentation should follow the same process as any other PR:
- Every developer who wrote the code should also write the Documentation.
- Documentation engineer will review the PR.
- After the PR is approved by the Doc-engineer it will be reviewed/edited by a technical writer.
- It will be reviewed once more and approved by Doc-engineer.
How to add pages
For getting started pages and developer guides:
-
Using Git, clone the repo:
git clone https://github.com/jina-ai/docs. -
Create a git new branch:
git checkout -b fix_pods. -
Use a template from the page_templates folder. We want to have an uniform structure in all of our docs, so we provide two templates for you to use:
- The How-to Documentation is for concrete guidelines. For topics that can be better explained step-by-step.
- The explanatory articles are to explain theory and background without any how-to details.
-
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 as reviewers for your PR. One product manager and one documentation engineer.
You can use Markdown or reStructuredText format. To preview how the docs website will look with your changes, navigate to checks and click 'preview with netlify'. After the pull request is merged, the website will automatically update.
Extra guides
- A guide to RST can be found here.
- A guide to MD formatting can be found here [Note that MD is more limited in functionality then RST].
Updating Docstrings
See details here.
Jina style guide
All documentation should follow this style guide.
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