Comments (4)
I think we'll have a couple of different audiences for documentation: RustPython end-users (i.e. Python developers) and people interested in RustPython internals (i.e. Rust developers). The former are more likely to be comfortable with Sphinx, and the latter with rustdoc.
Given the current state of development, I would lean towards using rustdoc. We can consider if we want to produce more Python-developer-friendly once we're in a state where it's actually feasible to use RustPython without knowing about the internals/the current state of development.
from rustpython.
That sounds reasonable to me. I don't have much experience with either tool.
from rustpython.
I agree with @OddBloke that rustdoc is probably favourable here but my preference would be doing this in the docs
directory of this repository, that way documentation can be maintained along with code.
from rustpython.
I'm looking to take on some documentation tasks to better familiarize myself with the internals. and it would be nice to get a clear answer on this question.
It appears the current state of the documentation is split between inline comments and some markdown files in the docs/
directory which also contains some presentation slides.
while it might be cleaner to document the project separately from the code rustdoc does not yet support this. we could of course not use rustdoc
but it seems a waste to have to spend the documentation effort and have to do all the relevant internal linking manually when rustdoc
can do it for us.
There is an unstable #![feature(external_doc)]
to include external documentation tracked by rust-lang/rust#44732 .
this would let us use #[doc(include = "external-doc.md")]
if some inline documentation gets too long and breaks the flow of reading the source too much.
Or #[doc(include = "../doc/external-doc.md")]
would allow a doc
folder to live next to the src
folder of each crate.
If moving forward with inline documentation is ok what sections do people feel could benefit most from some friendly documentation? personally I feel that the macros in use would be a good place to start as that would greatly aid in helping understand the project code better.
from rustpython.
Related Issues (20)
- how to run python module
- Extremely high memory consumption HOT 2
- zlib not found after install with `--features ssl`
- Trying to jit fibonacci function results in JitError: function can't be jitted
- Fix Windows CI HOT 3
- Investigate test_set.TestFrozenSet.test_hash_effectiveness performance
- Make vm.import_from_str() so we can import string python programs as modules HOT 1
- RustPython Slow to Normal Python HOT 2
- Add `__buffer__` and `__release_buffer__` methods to builtin types
- `format()` does not support locales for 'n' presentation type HOT 1
- Failed cargo install with SSL feature under linux (RustPython 0.3.0) HOT 9
- Dictionary order influences parseability HOT 3
- AttributeError: module 'typing' has no attribute 'Unpack'
- Compile error: cannot transmute between types of different sizes, or dependently-sized types [E0512] HOT 2
- Fix failing unit tests HOT 7
- UTF8 encoding messy code HOT 2
- "static type has not been initialized" when type lives in another module HOT 3
- error[E0635]: unknown feature stdsimd
- Using underline in an interactive environment cannot obtain the value of the last input expression. HOT 1
- Fix test for test_field_metadata_custom_mapping HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from rustpython.