Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] reorganize docs/ #4908

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

tangent-vector
Copy link
Contributor

This change attempts to slot the existing files under docs/ into a hierarchy that is more suitable for subsequent additions and improvements.

The core idea is to define a set of directories under docs/ that more clearly indicate where particular kinds of documentation can be found (and should go, when writing new docs):

  • compiler/ : docs related to the Slang compiler

  • compiler/command-line/ : docs related to slangc

  • compiler/implementation/ : contributor-facing docs on parts of the compiler implementation.

  • contributor/ : general contributor-facing docs

  • gfx/ : docs about gfx

  • gfx/guide : the gfx user's guide

  • gpu-feature/ : docs on specific GPU API features and how they are exposed and implemented.

  • historical/ : docs that are no longer relevant, but might not be good to delete entirely

  • language/ : docs related to the Slang language

  • language/guide/ : the Slang language user's guide

  • language/reference/ : the in-progress language reference

  • proposals/ : place for language/API/etc. proposals that should go through a more involved design/review process

  • stdlib/ : docs about the types/functions/etc. exposed by the Slang standard library

  • target/ : docs pertaining to specific targets, and feature support across targets

One obvious missing piece here is:

  • compiler/api/ : docs (guide and reference) for using the Slang compiler via its API

This change attempts to slot the existing files under `docs/` into a
hierarchy that is more suitable for subsequent additions and
improvements.

The core idea is to define a set of directories under `docs/` that
more clearly indicate where particular kinds of documentation can be
found (and should go, when writing new docs):

* `compiler/` : docs related to the Slang compiler

* `compiler/command-line/` : docs related to `slangc`

* `compiler/implementation/` : contributor-facing docs on
parts of the compiler implementation.

* `contributor/` : general contributor-facing docs

* `gfx/` : docs about `gfx`

* `gfx/guide` : the `gfx` user's guide

* `gpu-feature/` : docs on specific GPU API features and how they are
exposed and implemented.

* `historical/` : docs that are no longer relevant, but might not be
good to delete entirely

* `language/` : docs related to the Slang language

* `language/guide/` : the Slang language user's guide

* `language/reference/` : the in-progress language reference

* `proposals/` : place for language/API/etc. proposals that should go
through a more involved design/review process

* `stdlib/` : docs about the types/functions/etc. exposed by the Slang
standard library

* `target/` : docs pertaining to specific targets, and feature support
across targets

One obvious missing piece here is:

* `compiler/api/` : docs (guide and reference) for using the Slang
compiler via its API
@csyonghe
Copy link
Collaborator

We must update all references from main README and other docs e.g. build/conttribution guide and from shader-slang.org before merging this change.

@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants