Comments (5)
So here's a plan that I think would work well, in two steps:
First step, start generating the docs with pdoc. This tool will generate our documentation from the docstrings in each repo, so there is no need to do anything manual like what we are currently doing, and no extra code or config needs to be added to repos themselves. pdoc also has some really neat features like a live server for editing docs, and it can export to md/html. This requires a change in the release pipeline, and possibly a few non-functional tweaks to module source. I'll plan to add a CI check because pdoc will attempt to import everything even when it wouldn't be imported by default, and we have some hidden modules that aren't directly importable and will need to be fixed.
Second step, we've raised the idea of versioning our docs before. The default templates do not allow us to do that currently, but I think it would be very easy to modify the templates to have a header bar where we can add some branding, a version selector, and dark mode toggle for good measure. Since the version list will be dynamic, we can serve up a versions.json file or something and use javascript to parse it, or we could do something with frames if we want to avoid using JS unnecessarily.
Better idea, let's keep with sphinx, and get the docs on readthedocs. They support open source projects for free, and deal with things like versioning for us. They also support custom domains so we can still do api.angr.io, and we could set up each project to be in a subdirectory. RTD will automatically build our docs for us based on tagged releases, so I would be able to effectively remove angr-doc from the release process.
Thoughts @ltfish @rhelmot @mborgerson?
from angr-doc.
Summary from an offline discussion:
go for it dude
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 is complete! Took less than a year, even.
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
- 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.