CarperAI / CarperAI/trlx

Improve Documentation Process

Open
#176 0 comments 2 reactions 0 assignees View on GitHub
feature request
Dominant language
Python
Stars
4.8k
Forks
487
PR merge metrics
No merged PRs in 30d

Description

### 🚀 The feature, motivation, and pitch

# TLDR
- [ ] change: use google doc format for python
- [ ] add: better documentation generation logic to have a good-looking website
- [ ] add: improve the documentation by adding missing docstring to key functions

There are a few reasons why the Google Style documentation format is popular among machine learning projects like PyTorch and JAX:

Consistency: By using a standardized documentation format, it is easier for users to understand and use different projects, as the documentation for each project will follow the same basic structure and conventions. This can be especially helpful for machine learning projects, which often have complex APIs and can be difficult to learn and use.

Readability: The Google Style documentation format is designed to be easy to read and understand, with clear guidelines for formatting and organizing information. This can make it easier for users to find the information they need and learn how to use a project.

Maintenance: Using a standardized documentation format can also make it easier for developers to maintain and update the documentation for a project. It is easier to make changes and add new information when the documentation follows a consistent format.

Overall, the Google Style documentation format is popular because it helps to improve the usability and maintainability of machine learning projects like PyTorch and JAX.

References:
- [PEP 257](https://peps.python.org/pep-0257/)
- [Google Opensource](https://google.github.io/styleguide/pyguide.html)
- [PYTORCH](https://github.com/pytorch/pytorch/wiki/torch.nn-Module-Documentation-Style-Guide)

### Alternatives

There are a few alternatives to the Google Style documentation format for Python projects:

Sphinx: Sphinx is a popular tool for generating documentation for Python projects. It uses reStructuredText as its markup language and can generate documentation in various formats, including HTML, LaTeX, and PDF.

Epydoc: Epydoc is a tool for generating API documentation for Python modules based on their docstrings. It can generate documentation in HTML or PDF format.

NumPy/SciPy documentation style: The NumPy and SciPy projects have their own documentation style based on reStructuredText and follow specific guidelines for formatting and organizing information. This style is commonly used in other scientific computing projects in Python.

There are many other documentation styles and tools that are used in Python projects, and the choice of which to use often depends on the needs and preferences of the project and its contributors.

### Additional context

Documentation for a Python project can be read by a wide range of people, including developers, users, and contributors. The skills level of the readers can vary widely, from beginner programmers to experienced professionals.

Typically, users of a Python project will be looking for information on how to install, configure, and use the project. They may have a variety of skills levels, depending on their familiarity with Python and the specific domain the project is related to.

Developers and contributors to a Python project will often be looking for more detailed information on the implementation and design of the project. They may have a higher level of programming skills and be interested in understanding how the project works, in order to contribute code or bug fixes.

In general, it is useful for readers of documentation to have a clear understanding of the purpose and capabilities of the project, as well as information on how to get started using it. Detailed instructions, examples, and explanations of key concepts can also be helpful for users and developers.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.