Proposed improved documentation layout - this is what I'm aiming at

mooseman · December 31, 2024, 7:37am

Hi all -

Below are the topic headings that I’ve got as part of the improved docs layout “proof of concept / prototype” that I’ve been working on.

An admission - these are AI-generated but I think that AI can actually be useful in this instance to generate the headings that you then put the “beef” of the detailed documentation under.

Anyway - here is the “tree” for the main docs -


Introduction

    What is Zig?
    Key Design Philosophies
        Minimalism
        Predictability
        Explicitness
        Performance
    Language Versions & Roadmap

Getting Started

    Installation
        Downloading Prebuilt Binaries
        Building Zig from Source
        Verifying Your Installation

    Hello World
        zig run vs. zig build-exe
        Basic Project Structure

    Compiler Overview
        LLVM-based Compiler
        Stage2 (Self-Hosted) Compiler
        Supported Targets & Cross-Compilation

Build Process 

    Overview of zig build
        Why Use the Zig Build System?
        Project Layout & build.zig Files

    The build.zig File in Detail
        Declaring Executables
        Declaring Libraries (Static, Shared)
        Adding Dependencies
        Setting the Target Triple (Architecture, OS, ABI)
        Build Modes (Debug, ReleaseSafe, ReleaseFast, ReleaseSmall)

    Command-Line Usage
        zig build Subcommands (test, run, exe, lib, docs)
        Verbosity, Logging, & Other Flags
        Controlling Compiler Warnings/Errors

    Advanced Build Topics
        Custom Build Steps (e.g., code generation, resource compilation)
        Cross-Compilation Workflows
        Linking, Library Paths, and System Dependencies
        Using External C/C++ Code (.h & .c files, linking libs)
        Caching and Incremental Builds
        Build Artifacts (Output Paths, Intermediate Files)

    Scripting & Tooling
        Writing Custom Commands in build.zig
        Environment Variables & Configuration
        Packaging & Distribution (Prebuilt Binaries, .tar.gz, Docker)

Language Basics

    Variables and Constants
        var vs. const
        Block Scopes
        Shadowing

    Naming Conventions
        Identifiers & Style
        Module / File Names

    Comments and Documentation
        Single-line & Multi-line Comments
        Doc Comments (///)

    Code Organization
        Files & Modules
        Package Imports (@import, relative/absolute paths)

Data Types

    Primitive Types
        Integers (Signed/Unsigned, Fixed-Width, comptime_int)
        Floating-Point (f16, f32, f64, comptime_float)
        Booleans
        Characters (u8 code points)

    Compound Types
        Arrays & Slices
            Fixed-Size Arrays
            Slices ([]T, [*]T)

        Strings
            []const u8 vs. [*]const u8
            Null-Terminated Strings ([:0]const u8)

        Tuples

        Structures (struct)
            Fields & Field Access
            Anonymous Structs

        Enumerations (enum)
            Simple Enums
            C-like Enums
            Tagged Unions

        Unions
            Union Declarations
            Discriminants

    Pointers
        Unsafe vs. Safe Pointers
        Sentinel-Terminated Pointers
        Alignment & Address Spaces

    Optionals (?T)
        Usage & Unwrapping
        Comparisons with Null

    Error Unions (!T)
        Defining and Propagating Errors
        Error Sets
        try and catch

Control Flow

    If Statements & Expressions
        if / else syntax
        Optional chaining (if (optional) |value| {...})
        Inline if-expressions

    While Loops
        Basic while Conditions
        while (condition) |item| {...} pattern
        Breaking early with break

    For Loops
        Iterating over Arrays, Slices, Ranges
        Index & Value Variables

    Ranges
        Numeric Ranges
        Using with for

    Break & Continue
        Breaking out of Loops
        Skipping Iterations

    Switch Statements
        Pattern Matching with Enums, Tagged Unions, etc.
        Exhaustive vs. Non-Exhaustive Switch

Memory Management

    Allocators
        Standard Allocators (std.heap.page_allocator, std.heap.ArenaAllocator, etc.)
        Creating Custom Allocators
        Lifetime Considerations

    Manual Memory Control
        Allocating Arrays, Slices, Structs
        Freeing & Resizing

    Pointers & Slices Revisited
        Pointer Arithmetic
        Slicing Arrays

    Working with Zero-Cost Abstractions
        Minimizing Runtime Cost
        Ensuring Safety

Error Handling

    Declaring Errors
        error{SomeError, AnotherError}
        error.UnexpectedEOF

    Error Propagation
        Using try/catch
        Error Unions (!T)
        return error.SomethingBad

    Handling Errors
        Pattern Matching with switch
        Using catch |err| {...}

    Defer & Cleanup
        defer statements for resource cleanup
        Error-Safe Resource Management

Compile-Time Features

    comptime Keyword
        Compile-Time Conditionals
        Compile-Time Loops

    Compile-Time Functions
        fn foo(comptime x: T) ...
        Evaluating Functions at Compile Time

    Reflection & Metaprogramming
        @typeInfo, @typeName, @field
        Generics / Parameterized Code

    Inline Assembly
        Syntax, supported instructions
        Safety & Constraints

Concurrency & Asynchronous I/O

    Async Functions
        async fn basics
        await usage

    Suspend & Resume
        Cooperative Concurrency
        Event Loop Integration

    Channel & Queue Abstractions
        Passing Data Between Tasks
        std.Channel (if available in your Zig version)

    Example: Asynchronous Network Operations

Standard Library Essentials

    Overview of std
        Modules & How to Import

    Common Modules
        std.math (math functions)
        std.fs (file system handling)
        std.mem (memory utilities)
        std.testing (testing utilities)
        std.time (time utilities)

    Data Structures in std
        ArrayList, ArrayHashMap, LinkedList, etc.
        Usage Examples & Memory Allocation

    Utilities & Helpers
        std.debug (logging, printing)
        std.os (operating system calls)
        std.process (launching processes)

Interfacing with C/C++

    C Headers & FFI
        @cImport and @cInclude
        Linking against system libraries

    Calling Zig from C
        Generating .h files with zig translate-c

    Mixed Projects
        Organizing Zig + C/C++ code
        Build System Integration

Testing & Debugging

    Test Declarations
        test "description" {...}
        Running Tests with zig test

    Test Organization
        Multiple Test Files, Modules
        Using std.testing Assertions

    Debugging
        Compiler Flags (-femit-llvm-ir, -fno-strip)
        Using LLDB or GDB
        Print Debugging with std.debug.print

Deployment & Distribution

    Cross-Compilation in Depth
        Specifying --target (CPU, OS, ABI)
        Building Static vs. Shared Libraries
        Packaging for Multiple Platforms

    Optimization Modes
        Debug
        ReleaseSafe
        ReleaseFast
        ReleaseSmall

    Stripping Symbols & Minimizing Binary Size

    Reproducible Builds

Advanced Topics

    Using Zig as a Linker
        zig cc, zig c++ commands
        Wrapping External Toolchains

    Generic Programming
        Type Parameters
        comptime techniques

    Bit Manipulation
        Packed Structs, Bitfields
        Endianness

    Inline Functions & Builtins
        @import, @sizeOf, @alignOf, @offsetof, etc.

    Performance Tuning
        Measuring Performance
        Profiling (perf, instruments)
        Allocation Patterns

Tooling Overview

    zig fmt (Formatter)
    zig translate-c (C to Zig)
    zig ast-check (Syntax & Semantic Checks)
    zig targets (List Supported Targets)
    zig env (Environment Info)

Documentation Generation

    Using zig build docs
        Generating HTML
        Configuring Output Location

    Embedding Comments & Examples
        Best Practices for Doc Comments

    Linking to Standard Library Docs

Best Practices & Conventions

    Coding Style
        Naming, Formatting, Module Layout

    Memory Safety & Lifetime Management
    Error Handling Conventions
    Testing & Continuous Integration

    Contributing to Zig
        Reporting Issues
        Opening Pull Requests
        Community Resources (Discord, GitHub Discussions)

Further Reading & Resources

    Official Zig Language Reference
    Zig Community Projects & Packages
    External Tutorials & Guides
    Language Internals (Compiler Architecture, IR)

… and here is the tree for part of the standard library - the Build doc headings -


build
        Builder
            Builder.init
            Builder.setTarget
            Builder.setBuildMode
            Builder.getInstallPrefix
            Builder.addExecutable
                Executable
                    Executable.init
                    Executable.addObjectFile
                    Executable.linkSystemLibrary
                    Executable.linkFramework
            Builder.addLibrary
                Library
                    Library.initStatic
                    Library.initShared
            Builder.addSharedLibrary
            Builder.addStaticLibrary
            Builder.addTest
                TestStep
                    TestStep.init
                    TestStep.addDependency
            Builder.addObjectFile
                LibExeObjStep
                    LibExeObjStep.addObjectFile
                    LibExeObjStep.addLibraryPath
                    LibExeObjStep.linkSystemLibrary
                    LibExeObjStep.linkFramework
            Builder.linkSystemLibrary
            Builder.linkFramework
            Builder.installArtifact
                InstallStep
                    InstallStep.init
                    InstallStep.setPath
                    InstallStep.setTargetDir
            Builder.addInstallStep
            Builder.addRunStep
                RunStep
                    RunStep.init
                    RunStep.addArg
                    RunStep.addEnv
            Builder.addCommand
                Command
                    Command.init
            Builder.overrideStdSpecialStrings
        Step
            Step.init
            Step.addDependency
            Step.getDependencies
            Step.make
            Step.run
            CompileStep
                CompileStep.init
                CompileStep.setOutputPath
                CompileStep.addObjectFile
                CompileStep.addLibraryPath
                CompileStep.linkSystemLibrary
                CompileStep.linkFramework
            RunStep
                RunStep.init
                RunStep.addArg
                RunStep.addEnv
            InstallStep
                InstallStep.init
                InstallStep.setPath
                InstallStep.setTargetDir
            TestStep
                TestStep.init
            Command
                Command.init
        Mode
            Mode.Debug
            Mode.ReleaseSafe
            Mode.ReleaseFast
            Mode.ReleaseSmall
        Library
            Library.initStatic
            Library.initShared
            Library.step
        Executable
            Executable.init
            Executable.step
        LibExeObjStep
            LibExeObjStep.addObjectFile
            LibExeObjStep.addLibraryPath
            LibExeObjStep.linkSystemLibrary
            LibExeObjStep.linkFramework
            LibExeObjStep.finalize
        Dep
            Dep.init
            Dep.setName
            Dep.setVersionRange
            Dep.usePkgConfig
        PkgConfig
            PkgConfig.init
            PkgConfig.addLibPath
            PkgConfig.linkSystemLibrary
        Options
            Options.parse
            Options.addOption
            Options.addEnumOption
            Options.addCommand
            Options.getOptionValue
            Options.getEnumOptionValue
        Target
            Target.init
            Target.native
            Target.parse
            Target.cpu_arch
            Target.os_tag
            Target.abi
        Toolchain
            Toolchain.init
            Toolchain.linkSystemLibrary
            Toolchain.getCCompiler
        Config

My aim is that if/when the detailed documentation is done under those headings, the layout would look similar to this Python documentation page -

You can imagine that once there is detailed documentation and example code under these headings, this kind of layout would give an easy-to-understand and easy-to-use set of documentation.

By the way - for the HTML code and actual Zig code examples, I want to have both of those be 100 percent human-generated, not A.I.

Anyway, comments welcome - I hope you’ll be gentle with me…

Cheers -
mooseman

mooseman · January 11, 2025, 11:14pm

Hi all -

An update here - the proof-of-concept layout is now complete.
This is very much aimed at the Zig standard library documentation and integrating it into an easy-to-read, easy-to-understand and use package.

I’ve even included themes - note the “theme selector” dropdown at the top-right.
Not strictly needed but a fun thing to include.

Note - everything is AI-generated, including the documentation text itself.
I did mention that the inspiration for the layout was the Python documentation but I had a quick look at that page’s layout code (after completion of this stuff) and it is a lot more complex (for whatever reason) than the HTML and CSS behind this layout.

If there is enough interest, I’ll look at putting this on Github but if I do that, I’m thinking of changing the content to something non-Zig-related (say, cars) so as not to infringe on copyright or “step on toes” as it were.
( Please let me know if I don’t need to do that and can leave it as-is.
I would in that case clearly mark it as “unofficial documentation” ).

The main thing with all this is the layout, so if I do put this on Github (as a “documentation template”) I will make it “public domain” under the Unlicense and/or CC0.

Anyway - keen to hear what you think. Please be gentle with me…

Cheers -

mooseman

Cluster444 · January 12, 2025, 1:54am

I’m all for an upgrade of the docs, it’s very terse and hard to search atm. I’m kind of old school, so I’m used to it, but we need better if we want to be attractive to new waves of devs.

I think this is one of the places that Rust did very well. Consistent documentation system, and right now the langref and stdlib could use some love. They feel very 1990s.

What I want most of documentation is
→ Searchability - specifically fuzzy searching is a huge win.
→ Comments - Maybe I’m that old school, but PHP 3 docs were awful and the comments were an absolute gold mine. Maybe that’s too hard today with bots…
→ Bookmarking? Usually requires auth/account, maybe someone can be creative here?

Personally I think this needs to be a serious “epic” type of undertaking for Zig if we want to get stronger adoption.

mooseman · January 12, 2025, 2:19am

Hi Cluster444 - thanks very much for your reply!

Agreed. I think an upgrade of the docs - particularly the standard library docs - would be good. I just find those docs very difficult to follow.
I think that if the standard library docs were done in a similar way to the screenshot (where you can see everything at once on the left-hand side), that would make them much easier to follow and use.

The “main” Zig language documentation already uses that approach -

If there were a “tab” or button on that page to go to a similarly-laid-out standard library page, that would really give a cohesive, easy to read and easy to use set of documentation.

Cheers - thanks again!

mooseman

Cluster444 · January 12, 2025, 3:20am

I actually think the lang ref and std lib have the opposite layouts of what they should have.

The sidebar is ok on lang ref but much more useful for std lib. But if I had to choose I’m missing the sidebar on stdlib the most.

and

Are a couple of good examples. Rails 8 recently updated their doc layouts and they’re pretty useful. The reference has large sections around topics instead of one giant page that is hard to find stuff in. And the lib is searchable, but has the sidebar to filter separate from the details you’re viewing.

Too often on zigs std lib I’m wanting to scroll functions and view details and I’m opening 48 tabs which eventually grinds my laptop to a halt, which I wouldn’t need to do as much if there was a sidebar.

GigaGrunch · January 12, 2025, 9:12am

Depends on where they should be stored. You could just store them locally and need no account or anything.

nurpax · January 12, 2025, 9:45am

IMO std lib’s problem is lack of content, not its layout. I imagine the lack of content is due to being busy with other things and not wanting to commit time to writing about something that’s going to change anyway.

Hopefully at some point sites like https://zig.guide/ would become redundant as information on how to use f.ex. std lib container types would be included as examples in the std lib docs.

mooseman · January 12, 2025, 7:25pm

Hi nurpax - thanks for your reply!

For myself, I don’t find the current layout of the std lib docs helpful or easy to use. I’ll give a use-case.
I have a project in which I had a lot of errors with the Build script - errors of the type "Module Build has no member named “foo” " - that kind of thing.
The current layout of std lib docs makes it much harder than it needs to be to find the solution for an error like that.

If the std lib doc had a layout like the one in the screenshot, you can almost instantly see the complete structure of the Build module and all its valid members, along with valid syntax and example code for each part of it.
Much easier to use, IMO. That’s the kind of use-case I’m thinking of.

The kind of thing where you get an error “Foo has no member named bar”.
You’re thinking “Ok then, what are the valid members of foo?”
The layout as shown in the screenshot would be much better for answering that kind of question IMO.

Just my 2c worth… thanks again!

mooseman

Cluster444 · January 14, 2025, 7:52pm

Right now, it’s easier to use Github than it is to use the std lib site. I do 99% of my lookups there because of how awful it is to navigate the std lib site.

mooseman · January 16, 2025, 7:58am

Yes, I know what you mean, Cluster444! Agreed!

It’s a pity. Zig could have a really nice, inviting, easy-to-use set of documentation if the “sidebar approach” were used.
The main language doc already uses that approach.
It’s just a case of building on that with the std lib documentation.

I’ll try to get my proof-of-concept up on Github in the next few days.
People will then be able to actually get their hands on and play with the layout that I’ve shown. That’ll show what’s possible.

Bye for now -
mooseman