This repo contains all the tools to generate the English and Chinese version of the official website for PaddlePaddle (an easy-to-use, efficient, and scalable distributed deep learning platform). Tied with Django, these tools augment Sphinx's documentation generation capabilities.
The tutorials here guide you to setup the website locally, so you can see exactly how your contributions will appear on paddlepaddle.org.
-
Download / clone ONLY the relevant repos with content and code that you want to update and test (if you don't already have them):
(since this repo does not hold the content rendered on website)
- PaddlePaddle (contains all articles AND codebase to render the API documentation)
- Book (contains chapter pages)
- Models (contains the code to build models for different applications, including a few articles)
- Mobile (contains articles for building for mobile)
You can place these anywhere on the computer; at a later step we will tell PaddlePaddle.org where they are.
-
Pull PaddlePaddle.org into a new directory and install its dependencies.
But before that, make sure you have Python dependencies installed on your OS. For example, on an Ubuntu, run:
sudo apt-get update && apt-get install -y python-dev build-essential
Then,
git clone https://github.com/PaddlePaddle/PaddlePaddle.org.git cd PaddlePaddle.org/portal # To install in a virtual environment. # virtualenv venv; source venv/bin/activate pip install -r requirements.txt
Optional: If you plan on translating website content between English and Chinese for improving PaddlePaddle.org, install GNU gettext too.
-
Run PaddlePaddle.org locally.
Pass the list of directories you wish to load and build content from (options include
--paddle
,--book
,--models
, and--mobile
)./runserver --paddle <path_to_paddle_dir> --book <path_to_book_dir>
NOTE: In case of the --paddle directory, you may point to the specific API version directory (e.g.
<path to Paddle>/doc/fluid
or<path to Paddle>v2
).Open up your browser and navigate to http://localhost:8000. NOTE: Links may take a few seconds to load the first time around since they are probably being built.
All repositories support content contribution formatted as Markdown (the GitHub flavor). The Paddle repo, where majority of the documentation lies, also supports the reStructured Text format.
After you have gone through the installation steps above, here are the steps you need to take:
- Before you start writing, we recommend reviewing these guidelines on contributing content.
- Create a new
.md
(or.rst
, only in the case of Paddle) file OR edit an existing article's file within the appropriate directory of the repo you are contributing to. - To view the changes in your browser, click Refresh Content on the top-righthand side corner.
- To add it to a menu or change its position on the menu, click on the Edit menu button at the top of the left-handside menu on the page, to open the menu editor.
After you have built your new pybind
targets, and have tested your new Python API, you can continue with testing how your documentation strings and comments show up:
- We recommend reviewing these guidelines on contributing API documentation.
- Make sure that the built Python directory (containing
paddle
) is available in thePYTHONPATH
of where you are running./runserver
from. - On the specific "API" page you wish to update, click Refresh Content on the top-righthand side corner.
- To add it to a menu or change its position on the menu, click on the Edit menu button at the top of the left-handside menu on the page, to open the menu editor.
We appreciate contribution to various aspects of the platform and supporting content, apart from better presenting these materials. You may fork or clone this repository, or begin asking questions and providing feedback and leave bug reports on Github Issues. Please refer to Development Guide on how to get started.
PaddlePaddle.org is provided under the Apache-2.0 license.