Merge branch 'main' into add-readme

Author: gilteunchoi

README.md

@@ -1,42 +1,53 @@
 <img src="./logo.png" width="125" height="125" align="right" />
 
-# rustpython-doc
+# `__doc__` for [RustPython](https://rustpython.github.io/)
 
-This `rustpython-doc` package contains all `__doc__` database in forms of `docs.inc.rs`. 
+This is the `__doc__` attributes generator for objects written in RustPython.
 
-## How to update `__doc__` in RustPython
+It's composed of two parts of:
 
-Adding a remake in front of `[pyclass]` of `[pyfunction]` will simply make the documentation to themselves, however, we do not manually add docs anymore.
+- the `generate_docs.py` script that extracts the `__doc__` attributes from CPython to `docs.inc.rs`
+- the `rustpython-doc` rust crate that uses the `docs.inc.rs` file to create a documentation Database.
 
-> But we don't manually add docs anymore. We have an auto-generated document db.
-> 
-> The db is generated by scripts/generate_docs.py and applied to each object and functions by rustpython-doc::Database (search for crate::doc::Database::shared() in source code)
-> 
-> *- Originally posted by @youknowone in [RustPython#4205 (comment)](https://github.com/RustPython/RustPython/pull/4205)*
+This documentation database is then used by macros `pymodule` and `pyclass` macros of the rustpython-derive crate to automatically add the `__doc__` attribute.
 
-Therefore you must update `docs.in.rs`, if it is unnecessary to different from cpython's `__doc__`
+The `docs.inc.rs` database file can be generated with
 
-## How to update `docs.in.rs`
+    $ python -m venv gendocs
+    $ source gendocs/bin/activate
+    $ python -I generate_docs.py <path_to_RustPython> docs.inc.rs
+    $ deactivate
 
-To update  `__doc__` for newer python version:
+or using docker
 
-```
-$ python generate_docs.py {RustPython PATH} ./docs.inc.rs
-```
-This will iterate all stdlib modules to inspect their `__doc__`, updating your local `docs.in.rs` file. Since RustPython is only able to access the database in this online package, the changes must be merged into this branch.
+    $ docker pull python:slim
+    $ docker run python:slim python --version
+    Python 3.10.8
+    $ ls
+    __doc__  RustPython
+    $ docker run -v $(pwd):/RustPython -w /RustPython/__doc__ python:slim python generate_docs.py ../RustPython docs.inc.rs
 
-After that, update cargo:
+
+and do not forget to update cargo before the test
 ```
 $ cargo update
 ```
 ## Why the `__doc__` is not changed?
 
-### Check if it is related to the unclosed issue
-There is still some issue with `generate_docs.py`
-- https://github.com/RustPython/RustPython/issues/3973
+### Check the old documentation implemented with remarks are still exist
+RustPython prioritizes the user define documentation. Check if the old remarks are remaining in the source code. If it is, simply removing them could solve the issue.
+
+## Contributing
 
+Contributions are more than welcome, and in many cases we are happy to guide
+contributors through PRs or on gitter. Please refer to the
+[development guide](https://github.com/RustPython/RustPython/DEVELOPMENT.md) as well for tips on developments.
 
+## License
 
-### Check if the old remark documentation are not removed yet
+This project is licensed under the MIT license. Please see the
+[LICENSE](https://github.com/RustPython/RustPython/LICENSE) file for more details.
 
-RustPython prioritizes the user define documentation first. Check if old remarks remaining in the source code, and remove them.
+The [project logo](https://github.com/RustPython/RustPython/logo.png) is licensed under the CC-BY-4.0
+license. Please see the [LICENSE-logo](https://github.com/RustPython/RustPython/LICENSE-logo) file
+for more details.