Comments (8)
Will there also be a feature to show docs on the command-line, like go doc
? That's a feature I love having in Go, and really dislike the idea of documentation being only viewable through a web browser, especially for a low-level language.
from zig.
Progress of this is now underway:
- proof of concept
-
-fgenerate-docs
to generatedoc/
directory -
docs/
(plural) rename -
integrate with zig build system#3405 - render functions
-
render other types#3404 - type aware functions with error sets etc
- implement search
- add the concept of
pub
to semantic analysis dump - add stage1 parsing for doc comments
- add the concept of canonical paths to a package
- add the concept of canonical paths to a decl
-
implement source listings with links back to docs#3403 - add to semantic analysis dump references from generic functions to all the instantiated functions
- html/css style improvements
- keyboard shortcut helper dialog box
- add hyperlinks to search results
- struct fields
from zig.
Exciting!
I envision documentation generation as automatically happening as part of the normal build process. Rust's generated documentation looks great and has a usable search feature. I think doxygen is an example of what not to do.
Maybe as you mentioned, we get started on that self hosted compiler so we can do this feature in userland. As long as we keep the C++ implementation able to build the zig implementation, the bootstrapping process is simple enough.
Also related is the compiler outputting in some way data that is useful for IDEs such as an AST or a type table or something. @thejoshwolfe knows more about the requirements there.
from zig.
I'm starting to think it might make sense to go ahead and implement this in stage1:
- Prototypes reveal issues so that when doing the final implementation, we can make better informed design decisions. For example, if I hadn't prototyped copy-elision in stage1, it would have been a much lower quality implementation in self-hosted.
- We really need this feature. It's been too long without it already.
- Much of the work can be reused, such as the html and js.
from zig.
generate
doc/
directory
FYI, GitHub has an option to serve HTML from the /docs
(plural) directory.
from zig.
Started something preliminary here https://github.com/tiehuis/zig-docgen.
The idea right now is to generate some intermediate form (JSON) and pass that to some existing document generator. Working on writing the tokenizer in zig and a simplistic parser so may have some overlap with #89 eventually.
from zig.
FYI, GitHub has an option to serve HTML from the
/docs
(plural) directory.
Hmm, that's a pretty good reason to change it.
from zig.
from zig.
Related Issues (20)
- zig fetch -h should include examples
- std.Build.Cache.addDepFilePost should report the missing path when error.FileNotFound is encountered
- implement std.Progress for single-threaded mode
- std.Progress: add byte unit flag and resource scope; support throughput calculation HOT 2
- implement std.Progress IPC for WASI
- implement std.Progress IPC for Windows
- add support for targeting glibc 2.39
- Progress display is cut off horizontally HOT 2
- `zig fmt` outputs invalid syntax when formatting an error set with doc comments onto one line
- Latest master tarball is unable to build a stage4 zig HOT 3
- upperBound and lowerBound has inconsistent callback types HOT 1
- "offsetof" from C header does not handle union within struct HOT 3
- x86_64 backend miscomp
- When compiling for android, and linking libc, you will always hit a @compileError HOT 1
- Progress cuts off prints to the terminal HOT 6
- x86_64 backend `genSetReg called with a value larger than dst_reg`
- Crash when using ArrayList init with ArenaAllocator HOT 1
- error: NoSpaceLeft with MacOS target on x86 host HOT 2
- Thread.Pool cannot be spawned with !void function HOT 1
- New progress goes in the way of interactive CLI apps HOT 2
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 zig.