From 31da439b57951d0d61956f16c017ec61c95bf8dd Mon Sep 17 00:00:00 2001 From: Sean Silva Date: Sun, 20 Jan 2013 02:19:36 +0000 Subject: [PATCH] docs: Inline documentation structure into homepage. This brings back {Ctrl,Cmd}-f'ability, and makes some really bad organizational choices easier to see (and therefore fix). git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@172949 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/design_and_overview.rst | 35 --- docs/development_process.rst | 30 --- docs/index.rst | 422 ++++++++++++++++++++++++++++++++--- docs/mailing_lists.rst | 33 --- docs/programming.rst | 56 ----- docs/subsystems.rst | 108 --------- docs/userguides.rst | 110 --------- 7 files changed, 390 insertions(+), 404 deletions(-) delete mode 100644 docs/design_and_overview.rst delete mode 100644 docs/development_process.rst delete mode 100644 docs/mailing_lists.rst delete mode 100644 docs/programming.rst delete mode 100644 docs/subsystems.rst delete mode 100644 docs/userguides.rst diff --git a/docs/design_and_overview.rst b/docs/design_and_overview.rst deleted file mode 100644 index 2fc377f3aa4..00000000000 --- a/docs/design_and_overview.rst +++ /dev/null @@ -1,35 +0,0 @@ -LLVM Design & Overview -====================== - -.. toctree:: - :hidden: - - LangRef - GetElementPtr - -* :doc:`LangRef` - - Defines the LLVM intermediate representation. - -* `Introduction to the LLVM Compiler `_ - - Presentation providing a users introduction to LLVM. - -* `Intro to LLVM `_ - - Book chapter providing a compiler hacker's introduction to LLVM. - -* `LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation - `_ - - Design overview. - -* `LLVM: An Infrastructure for Multi-Stage Optimization - `_ - - More details (quite old now). - -* :doc:`GetElementPtr` - - Answers to some very frequent questions about LLVM's most frequently - misunderstood instruction. diff --git a/docs/development_process.rst b/docs/development_process.rst deleted file mode 100644 index 86d611cab99..00000000000 --- a/docs/development_process.rst +++ /dev/null @@ -1,30 +0,0 @@ -Development Process Documentation -================================= - -.. toctree:: - :hidden: - - MakefileGuide - Projects - LLVMBuild - HowToReleaseLLVM - -* :doc:`Projects` - - How-to guide and templates for new projects that *use* the LLVM - infrastructure. The templates (directory organization, Makefiles, and test - tree) allow the project code to be located outside (or inside) the ``llvm/`` - tree, while using LLVM header files and libraries. - -* :doc:`LLVMBuild` - - Describes the LLVMBuild organization and files used by LLVM to specify - component descriptions. - -* :doc:`MakefileGuide` - - Describes how the LLVM makefiles work and how to use them. - -* :doc:`HowToReleaseLLVM` - - This is a guide to preparing LLVM releases. Most developers can ignore it. diff --git a/docs/index.rst b/docs/index.rst index 6aefc86b10a..92421aaafc8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,54 +13,412 @@ research projects. Similarly, documentation is broken down into several high-level groupings targeted at different audiences: -* **Design & Overview** +LLVM Design & Overview +====================== - Several introductory papers and presentations are available at - :doc:`design_and_overview`. +Several introductory papers and presentations. -* **Publications** +.. toctree:: + :hidden: + + LangRef + GetElementPtr + +* :doc:`LangRef` + + Defines the LLVM intermediate representation. + +* `Introduction to the LLVM Compiler `_ + + Presentation providing a users introduction to LLVM. + +* `Intro to LLVM `_ + + Book chapter providing a compiler hacker's introduction to LLVM. + +* `LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation + `_ + + Design overview. + +* `LLVM: An Infrastructure for Multi-Stage Optimization + `_ + + More details (quite old now). + +* :doc:`GetElementPtr` + + Answers to some very frequent questions about LLVM's most frequently + misunderstood instruction. + +Publications +============ + +The list of `publications `_ based on LLVM. + +User Guides +=========== + +For those new to the LLVM system. + +NOTE: If you are a user who is only interested in using LLVM-based +compilers, you should look into `Clang `_ or +`DragonEgg `_ instead. The documentation here is +intended for users who have a need to work with the intermediate LLVM +representation. + +.. toctree:: + :hidden: + + CMake + HowToBuildOnARM + CommandGuide/index + DeveloperPolicy + GettingStarted + GettingStartedVS + FAQ + Lexicon + Packaging + HowToAddABuilder + yaml2obj + HowToSubmitABug + SphinxQuickstartTemplate + Phabricator + TestingGuide + tutorial/index + ReleaseNotes + Passes + YamlIO + +* :doc:`GettingStarted` + + Discusses how to get up and running quickly with the LLVM infrastructure. + Everything from unpacking and compilation of the distribution to execution + of some tools. + +* :doc:`CMake` + + An addendum to the main Getting Started guide for those using the `CMake + build system `_. + +* :doc:`HowToBuildOnARM` + + Notes on building and testing LLVM/Clang on ARM. + +* :doc:`GettingStartedVS` + + An addendum to the main Getting Started guide for those using Visual Studio + on Windows. + +* :doc:`tutorial/index` + + Tutorials about using LLVM. Includes a tutorial about making a custom + language with LLVM. + +* :doc:`DeveloperPolicy` + + The LLVM project's policy towards developers and their contributions. + +* :doc:`LLVM Command Guide ` - The list of `publications `_ based on LLVM. + A reference manual for the LLVM command line utilities ("man" pages for LLVM + tools). -* **User Guides** +* :doc:`Passes` - Those new to the LLVM system should first visit the :doc:`userguides`. + A list of optimizations and analyses implemented in LLVM. - NOTE: If you are a user who is only interested in using LLVM-based - compilers, you should look into `Clang `_ or - `DragonEgg `_ instead. The documentation here is - intended for users who have a need to work with the intermediate LLVM - representation. +* :doc:`FAQ` -* **API Clients** + A list of common questions and problems and their solutions. - Developers of applications which use LLVM as a library should visit the - :doc:`programming`. +* :doc:`Release notes for the current release ` -* **Subsystems** + This describes new features, known bugs, and other limitations. - API clients and LLVM developers may be interested in the - :doc:`subsystems` documentation. +* :doc:`HowToSubmitABug` -* **Development Process** + Instructions for properly submitting information about any bugs you run into + in the LLVM system. +* :doc:`SphinxQuickstartTemplate` - Additional documentation on the LLVM project can be found at - :doc:`development_process`. + A template + tutorial for writing new Sphinx documentation. It is meant + to be read in source form. -* **Mailing Lists** +* :doc:`LLVM Testing Infrastructure Guide ` - For more information, consider consulting the LLVM :doc:`mailing_lists`. + A reference manual for using the LLVM testing infrastructure. + +* `How to build the C, C++, ObjC, and ObjC++ front end `_ + + Instructions for building the clang front-end from source. + +* :doc:`Packaging` + + Advice on packaging LLVM into a distribution. + +* :doc:`Lexicon` + + Definition of acronyms, terms and concepts used in LLVM. + +* :doc:`HowToAddABuilder` + + Instructions for adding new builder to LLVM buildbot master. + +* :doc:`YamlIO` + + A reference guide for using LLVM's YAML I/O library. + +IRC +=== + +You can probably find help on the unofficial LLVM IRC. + +We often are on irc.oftc.net in the #llvm channel. If you are using the +mozilla browser, and have chatzilla installed, you can `join #llvm on +irc.oftc.net `_. + +Programming Documentation +========================= + +For developers of applications which use LLVM as a library. .. toctree:: - :maxdepth: 2 - - design_and_overview - userguides - programming - subsystems - development_process - mailing_lists - + :hidden: + + Atomics + CodingStandards + CommandLine + CompilerWriterInfo + ExtendingLLVM + HowToSetUpLLVMStyleRTTI + ProgrammersManual + +* :doc:`LLVM Language Reference Manual ` + + Defines the LLVM intermediate representation and the assembly form of the + different nodes. + +* :doc:`Atomics` + + Information about LLVM's concurrency model. + +* :doc:`ProgrammersManual` + + Introduction to the general layout of the LLVM sourcebase, important classes + and APIs, and some tips & tricks. + +* :doc:`CommandLine` + + Provides information on using the command line parsing library. + +* :doc:`CodingStandards` + + Details the LLVM coding standards and provides useful information on writing + efficient C++ code. + +* :doc:`HowToSetUpLLVMStyleRTTI` + + How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your + class hierarchy. + +* :doc:`ExtendingLLVM` + + Look here to see how to add instructions and intrinsics to LLVM. + +* `Doxygen generated documentation `_ + + (`classes `_) + (`tarball `_) + +* `ViewVC Repository Browser `_ + +* :doc:`CompilerWriterInfo` + + A list of helpful links for compiler writers. + +Subsystem Documentation +======================= + +For API clients and LLVM developers. + +.. toctree:: + :hidden: + + AliasAnalysis + BitCodeFormat + BranchWeightMetadata + Bugpoint + CodeGenerator + ExceptionHandling + LinkTimeOptimization + SegmentedStacks + TableGenFundamentals + DebuggingJITedCode + GoldPlugin + MarkedUpDisassembly + SystemLibrary + SourceLevelDebugging + Vectorizers + WritingAnLLVMBackend + GarbageCollection + WritingAnLLVMPass + TableGen/LangRef + +* :doc:`WritingAnLLVMPass` + + Information on how to write LLVM transformations and analyses. + +* :doc:`WritingAnLLVMBackend` + + Information on how to write LLVM backends for machine targets. + +* :doc:`CodeGenerator` + + The design and implementation of the LLVM code generator. Useful if you are + working on retargetting LLVM to a new architecture, designing a new codegen + pass, or enhancing existing components. + +* :doc:`TableGenFundamentals` + + Describes the TableGen tool, which is used heavily by the LLVM code + generator. + +* :doc:`AliasAnalysis` + + Information on how to write a new alias analysis implementation or how to + use existing analyses. + +* :doc:`GarbageCollection` + + The interfaces source-language compilers should use for compiling GC'd + programs. + +* :doc:`Source Level Debugging with LLVM ` + + This document describes the design and philosophy behind the LLVM + source-level debugger. + +* :doc:`Vectorizers` + + This document describes the current status of vectorization in LLVM. + +* :doc:`ExceptionHandling` + + This document describes the design and implementation of exception handling + in LLVM. + +* :doc:`Bugpoint` + + Automatic bug finder and test-case reducer description and usage + information. + +* :doc:`BitCodeFormat` + + This describes the file format and encoding used for LLVM "bc" files. + +* :doc:`System Library ` + + This document describes the LLVM System Library (``lib/System``) and + how to keep LLVM source code portable + +* :doc:`LinkTimeOptimization` + + This document describes the interface between LLVM intermodular optimizer + and the linker and its design + +* :doc:`GoldPlugin` + + How to build your programs with link-time optimization on Linux. + +* :doc:`DebuggingJITedCode` + + How to debug JITed code with GDB. + +* :doc:`BranchWeightMetadata` + + Provides information about Branch Prediction Information. + +* :doc:`SegmentedStacks` + + This document describes segmented stacks and how they are used in LLVM. + +* :doc:`MarkedUpDisassembly` + + This document describes the optional rich disassembly output syntax. + + +Development Process Documentation +================================= + + +Information about LLVM's development process. + +.. toctree:: + :hidden: + + MakefileGuide + Projects + LLVMBuild + HowToReleaseLLVM + +* :doc:`Projects` + + How-to guide and templates for new projects that *use* the LLVM + infrastructure. The templates (directory organization, Makefiles, and test + tree) allow the project code to be located outside (or inside) the ``llvm/`` + tree, while using LLVM header files and libraries. + +* :doc:`LLVMBuild` + + Describes the LLVMBuild organization and files used by LLVM to specify + component descriptions. + +* :doc:`MakefileGuide` + + Describes how the LLVM makefiles work and how to use them. + +* :doc:`HowToReleaseLLVM` + + This is a guide to preparing LLVM releases. Most developers can ignore it. + +Mailing Lists +============= + +If you can't find what you need in these docs, try consulting the mailing +lists. + +* `LLVM Announcements List + `_ + + This is a low volume list that provides important announcements regarding + LLVM. It gets email about once a month. + +* `Developer's List `_ + + This list is for people who want to be included in technical discussions of + LLVM. People post to this list when they have questions about writing code + for or using the LLVM tools. It is relatively low volume. + +* `Bugs & Patches Archive `_ + + This list gets emailed every time a bug is opened and closed, and when people + submit patches to be included in LLVM. It is higher volume than the LLVMdev + list. + +* `Commits Archive `_ + + This list contains all commit messages that are made when LLVM developers + commit code changes to the repository. It is useful for those who want to + stay on the bleeding edge of LLVM development. This list is very high volume. + +* `Test Results Archive + `_ + + A message is automatically sent to this list by every active nightly tester + when it completes. As such, this list gets email several times each day, + making it a high volume list. + Indices and tables ================== diff --git a/docs/mailing_lists.rst b/docs/mailing_lists.rst deleted file mode 100644 index d6ac9c730bd..00000000000 --- a/docs/mailing_lists.rst +++ /dev/null @@ -1,33 +0,0 @@ -Mailing Lists -============= - - * `LLVM Announcements List - `_ - - This is a low volume list that provides important announcements regarding - LLVM. It gets email about once a month. - - * `Developer's List `_ - - This list is for people who want to be included in technical discussions of - LLVM. People post to this list when they have questions about writing code - for or using the LLVM tools. It is relatively low volume. - - * `Bugs & Patches Archive `_ - - This list gets emailed every time a bug is opened and closed, and when people - submit patches to be included in LLVM. It is higher volume than the LLVMdev - list. - - * `Commits Archive `_ - - This list contains all commit messages that are made when LLVM developers - commit code changes to the repository. It is useful for those who want to - stay on the bleeding edge of LLVM development. This list is very high volume. - - * `Test Results Archive - `_ - - A message is automatically sent to this list by every active nightly tester - when it completes. As such, this list gets email several times each day, - making it a high volume list. diff --git a/docs/programming.rst b/docs/programming.rst deleted file mode 100644 index aa51130533b..00000000000 --- a/docs/programming.rst +++ /dev/null @@ -1,56 +0,0 @@ -Programming Documentation -========================= - -.. toctree:: - :hidden: - - Atomics - CodingStandards - CommandLine - CompilerWriterInfo - ExtendingLLVM - HowToSetUpLLVMStyleRTTI - ProgrammersManual - -* :doc:`LLVM Language Reference Manual ` - - Defines the LLVM intermediate representation and the assembly form of the - different nodes. - -* :doc:`Atomics` - - Information about LLVM's concurrency model. - -* :doc:`ProgrammersManual` - - Introduction to the general layout of the LLVM sourcebase, important classes - and APIs, and some tips & tricks. - -* :doc:`CommandLine` - - Provides information on using the command line parsing library. - -* :doc:`CodingStandards` - - Details the LLVM coding standards and provides useful information on writing - efficient C++ code. - -* :doc:`HowToSetUpLLVMStyleRTTI` - - How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your - class hierarchy. - -* :doc:`ExtendingLLVM` - - Look here to see how to add instructions and intrinsics to LLVM. - -* `Doxygen generated documentation `_ - - (`classes `_) - (`tarball `_) - -* `ViewVC Repository Browser `_ - -* :doc:`CompilerWriterInfo` - - A list of helpful links for compiler writers. diff --git a/docs/subsystems.rst b/docs/subsystems.rst deleted file mode 100644 index 7430c82f1ce..00000000000 --- a/docs/subsystems.rst +++ /dev/null @@ -1,108 +0,0 @@ -Subsystem Documentation -======================= - -.. toctree:: - :hidden: - - AliasAnalysis - BitCodeFormat - BranchWeightMetadata - Bugpoint - CodeGenerator - ExceptionHandling - LinkTimeOptimization - SegmentedStacks - TableGenFundamentals - DebuggingJITedCode - GoldPlugin - MarkedUpDisassembly - SystemLibrary - SourceLevelDebugging - Vectorizers - WritingAnLLVMBackend - GarbageCollection - WritingAnLLVMPass - TableGen/LangRef - -* :doc:`WritingAnLLVMPass` - - Information on how to write LLVM transformations and analyses. - -* :doc:`WritingAnLLVMBackend` - - Information on how to write LLVM backends for machine targets. - -* :doc:`CodeGenerator` - - The design and implementation of the LLVM code generator. Useful if you are - working on retargetting LLVM to a new architecture, designing a new codegen - pass, or enhancing existing components. - -* :doc:`TableGenFundamentals` - - Describes the TableGen tool, which is used heavily by the LLVM code - generator. - -* :doc:`AliasAnalysis` - - Information on how to write a new alias analysis implementation or how to - use existing analyses. - -* :doc:`GarbageCollection` - - The interfaces source-language compilers should use for compiling GC'd - programs. - -* :doc:`Source Level Debugging with LLVM ` - - This document describes the design and philosophy behind the LLVM - source-level debugger. - -* :doc:`Vectorizers` - - This document describes the current status of vectorization in LLVM. - -* :doc:`ExceptionHandling` - - This document describes the design and implementation of exception handling - in LLVM. - -* :doc:`Bugpoint` - - Automatic bug finder and test-case reducer description and usage - information. - -* :doc:`BitCodeFormat` - - This describes the file format and encoding used for LLVM "bc" files. - -* :doc:`System Library ` - - This document describes the LLVM System Library (``lib/System``) and - how to keep LLVM source code portable - -* :doc:`LinkTimeOptimization` - - This document describes the interface between LLVM intermodular optimizer - and the linker and its design - -* :doc:`GoldPlugin` - - How to build your programs with link-time optimization on Linux. - -* :doc:`DebuggingJITedCode` - - How to debug JITed code with GDB. - -* :doc:`BranchWeightMetadata` - - Provides information about Branch Prediction Information. - -* :doc:`SegmentedStacks` - - This document describes segmented stacks and how they are used in LLVM. - -* :doc:`MarkedUpDisassembly` - - This document describes the optional rich disassembly output syntax. - diff --git a/docs/userguides.rst b/docs/userguides.rst deleted file mode 100644 index e7e4518afcf..00000000000 --- a/docs/userguides.rst +++ /dev/null @@ -1,110 +0,0 @@ -User Guides -=========== - -.. toctree:: - :hidden: - - CMake - HowToBuildOnARM - CommandGuide/index - DeveloperPolicy - GettingStarted - GettingStartedVS - FAQ - Lexicon - Packaging - HowToAddABuilder - yaml2obj - HowToSubmitABug - SphinxQuickstartTemplate - Phabricator - TestingGuide - tutorial/index - ReleaseNotes - Passes - YamlIO - -* :doc:`GettingStarted` - - Discusses how to get up and running quickly with the LLVM infrastructure. - Everything from unpacking and compilation of the distribution to execution - of some tools. - -* :doc:`CMake` - - An addendum to the main Getting Started guide for those using the `CMake - build system `_. - -* :doc:`HowToBuildOnARM` - - Notes on building and testing LLVM/Clang on ARM. - -* :doc:`GettingStartedVS` - - An addendum to the main Getting Started guide for those using Visual Studio - on Windows. - -* :doc:`tutorial/index` - - Tutorials about using LLVM. Includes a tutorial about making a custom - language with LLVM. - -* :doc:`DeveloperPolicy` - - The LLVM project's policy towards developers and their contributions. - -* :doc:`LLVM Command Guide ` - - A reference manual for the LLVM command line utilities ("man" pages for LLVM - tools). - -* :doc:`Passes` - - A list of optimizations and analyses implemented in LLVM. - -* :doc:`FAQ` - - A list of common questions and problems and their solutions. - -* :doc:`Release notes for the current release ` - - This describes new features, known bugs, and other limitations. - -* :doc:`HowToSubmitABug` - - Instructions for properly submitting information about any bugs you run into - in the LLVM system. -* :doc:`SphinxQuickstartTemplate` - - A template + tutorial for writing new Sphinx documentation. It is meant - to be read in source form. - -* :doc:`LLVM Testing Infrastructure Guide ` - - A reference manual for using the LLVM testing infrastructure. - -* `How to build the C, C++, ObjC, and ObjC++ front end `_ - - Instructions for building the clang front-end from source. - -* :doc:`Packaging` - - Advice on packaging LLVM into a distribution. - -* :doc:`Lexicon` - - Definition of acronyms, terms and concepts used in LLVM. - -* :doc:`HowToAddABuilder` - - Instructions for adding new builder to LLVM buildbot master. - -* :doc:`YamlIO` - - A reference guide for using LLVM's YAML I/O library. - -* **IRC** -- You can probably find help on the unofficial LLVM IRC. - - We often are on irc.oftc.net in the #llvm channel. If you are using the - mozilla browser, and have chatzilla installed, you can `join #llvm on - irc.oftc.net `_. -- 2.34.1