keras-io

Introduction to the Keras.io Documentation Generator

The Keras.io Documentation Generator is a project dedicated to creating and updating the keras.io website. It serves as a crucial tool for developers and enthusiasts who wish to explore and contribute to the Keras community.

Setting Up a Local Copy of the Website

To get a local version of the keras.io website up and running, follow a few straightforward steps. Begin by installing the necessary Python packages using the command:

pip install -r requirements.txt

Make sure to update the Keras package to version 3.0.2 with the command:

pip install keras==3.0.2

Once the packages are ready, navigate to the scripts directory and use the following commands to generate and serve the website:

python autogen.py make
python autogen.py serve

For those who prefer using Docker, the process can be simplified:

docker build -t keras-io . && docker run --rm -p 8000:8000 keras-io

This will create and run a Docker image, serving the website at your local server.

Call for Contributions

The project thrives on community involvement. If you're interested in contributing new examples to keras.io, your input is highly valued. Contributions should align with current interests detailed in their call for contributions.

Fixing Existing Examples

If you identify a typo or small error in existing examples, you can directly edit parts of the files (.py, .md, and .ipynb) through a Pull Request (PR). For more substantial changes, initially update only the .py file for review before altering the other file formats.

Adding New Code Examples

When adding new examples, contributors use a concept called tutobooks. These are versatile scripts that exist in several formats: as a Python script, a Jupyter notebook, and a rendered webpage.

From a Jupyter Notebook

1. Save your notebook locally.

2. Convert it into a tutobook:

   python tutobooks.py nb2py path_to_your_nb.ipynb ../examples/vision/script_name.py
   

3. Edit the new Python script to ensure quality formatting and add relevant metadata in the header.

4. Use the command below to generate corresponding file formats:

   python autogen.py add_example vision/script_name
   

5. Submit a PR with your .py script and after approval, add the generated files.

Directly from a Python Script

1. Format your script using black.
2. Add introductory metadata headers.
3. Follow similar steps for generating additional formats and manage the PR process as detailed above.

Previewing and Running New Examples

To see how your example will appear on the website, you may run:

cd scripts
python autogen.py add_example vision/script_name

Ensure your code is efficient and doesn't result in prolonged execution times, as examples should be lightweight demonstrations.

Finally, serve the website:

python autogen.py make
python autogen.py serve

Navigate to 0.0.0.0:8000/examples to view your contribution.

File Management Guidelines

Certain folders like site/* and sources/* host autogenerated content and should not be manually edited. Only files such as templates/*.md (outside specific subdirectories) and certain Python scripts are open for direct modification.

By following these guidelines, contributors can efficiently expand and refine the keras.io documentation, enhancing its value as a comprehensive resource for the global Keras community.