Comments (8)
The closing of the two sphinx issues does not seem to have totally solved the problem they were supposed to solve, seeing as pyvex.Block.size is a link to some cfgfast member, so I opened a new PR.
from angr-doc.
This issue has been marked as stale
because it has no recent activity. Please comment or add the pinned
tag to prevent this issue from being closed.
from angr-doc.
This issue has been marked as stale
because it has no recent activity. Please comment or add the pinned
tag to prevent this issue from being closed.
from angr-doc.
This issue has been marked as stale
because it has no recent activity. Please comment or add the pinned
tag to prevent this issue from being closed.
from angr-doc.
The new mission, should we choose to accept it:
Having to maintain those rst files is a gigantic pain. We should have a system to autogenerate them so we no longer have to sync angr-doc PRs with every other PR. We should migrate whatever narrative documentation is left in the rst files into docstrings or the book.
The only unanswered question afaik is what to do about the structure that is added by the hand-crafted rst files. We currently have nice headers and intuitive orderings for all the modules within angr, pyvex, etc, and we'll be losing them if we move to autogeneration. Two options that jump out at me are: 1) disregard the ordering, nobody reads the api docs top to bottom, and 2) add some sort of metadata to docstrings so we know what order and heading to put them in.
from angr-doc.
disregard the ordering, nobody reads the api docs top to bottom
This.
from angr-doc.
I recently took a stab at this and got sorta stuck on making a decision. The two best options I could find are pdochttps://github.com/mitmproxy/pdoc) and sphinx. pdoc is the magic "here's a python module with docstrings, make me some html with no extra effort required". This is what I think we want, as it keeps the docs right in python source itself and doesn't require maintaining rsts. The other option was trying to improve the sphinx setup. The key benefit here is integration with readthedocs, as basically everything else about using sphinx was a negative. Notably there's very little automatic about it. While it can read docstrings, you have to at a minimum hand-write an automodule declaration for it, and the syntax is more complicated than markdown.
With that said, RTD does have beta support for using third party doc tools, with the downside of less integration, they cite the version flyout as an example. Publishing to RTD using pdoc to build is probably the best option forward, as it should be low maintenance and should be able to be implemented quickly.
from angr-doc.
Since api docs have been moved to project repos, I'm going to consider this complete, and then in time open new issues in the project repos regarding improving their documentation individually.
from angr-doc.
Related Issues (20)
- Unexpected behaviour between different versions while analyzing "beginner" binary HOT 1
- [help] why no solutions?
- why input length must multiply 4 in examples/b01lersctf2020_little_engine HOT 1
- Question: BVS, bytes, ASCII, constraints HOT 3
- Resolve automatically HOT 15
- Remove references to Layer7 and other Surveyor solves HOT 1
- CFG Emulated "None type" Node HOT 2
- Swapped find and avoid on sim_mgr.explore when using argv claripy HOT 1
- where can i find the source code of the folder "example"? HOT 1
- little_engine example not working for me HOT 9
- Error/inconsistency handling arm code between angr versions
- Add concatenating constraints to cheatsheet HOT 2
- insomnihack fail to find a symbolic buffer HOT 2
- `test_apidoc.test_lint_docstrings` fails under python 3.8 HOT 5
- `test_examples.test_defcon2016quals_baby_re` is timing out in CI HOT 3
- Testing the java_androidnative1 example failed with error HOT 3
- Move API docs to project repos. HOT 5
- Install information is out of date and sometimes incorrect HOT 1
- Migrate gitbook docs to api docs HOT 1
- driller's approach page cannot find 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 angr-doc.