boost/website-v2-docs
2
0
Fork 0
mirror of https://github.com/boostorg/website-v2-docs.git synced 2026-01-19 04:42:17 +00:00
Code Issues Projects Releases Wiki Activity
Files
965f1c4506be5a61e12869f4f16267de78f2d035
website-v2-docs/contributor-guide/modules/ROOT/pages/docs/content.adoc
alandefreitas 965f1c4506 docs(contributor-guide): update Antora guide
2024-09-26 19:21:13 -03:00

601 lines
11 KiB
Plaintext
Raw Blame History

////
Copyright (c) 2024 The C++ Alliance, Inc. (https://cppalliance.org)
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Official repository: https://github.com/boostorg/website-v2-docs
////
= Documentation Content Structure
:navtitle: Content
It is not a _requirement_ for a Boost library for the documentation to adhere to the following structure.
However, it is listed here as a guide, if needed.
The following structure for Boost library documentation should work for most libraries.
Take each section in the order listed below, and fill in the details for your library.
Alternatively, if you want your documentation to be closer to the pass:[C++] Standard, refer to xref:docs/components.adoc[].
Although library documentation can use any format in
xref:docs/layout.adoc#standalone-documentation[standalone documentation], the instructions on this page will use AsciiDoc as the format.
Visit https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference,window=_blank] for more information on AsciiDoc syntax.
Where you see `<LibraryName>` in the templates below, replace with the name of your library.
== Overview
Provide a brief overview of the focus and features of your library.
Mention the portability of the library, platforms and compilers.
List dependencies.
A developer should have a good idea if the library is right for their project, after reading your Overview.
Note that footnote references link to the footnotes section, and the entries in the footnote section link back to the references.
=== Overview Template
[source,asciidoc]
----
== Overview
Add an introduction to your library here. Refer to previous libraries on the content of an Overview.
== First Topic
[#footnote1-location]
text
text that requires a footnote. link:#footnote1[(1)]
== Second Topic
[#footnote2-location]
text
text that requires a footnote. link:#footnote2[(2)]
== Third Topic
text
== Footnotes
[#footnote1]
link:#footnote1-location[(1)]: footnote 1 text
[#footnote2]
link:#footnote2-location[(2)]: footnote 2 text
----
== Design Rationale
A Rationale provides a description of the motivation behind the library.
Describe the current problems that exist, and the goals of the library in addressing those problems.
=== Rationale Template
[source,asciidoc]
----
== Introduction
Add an introduction to the rationale for your library here. Refer to previous libraries on the content of a Rationale.
== First Topic
[#footnote1-location]
text
text that requires a footnote. link:#footnote1[(1)]
== Second Topic
[#footnote2-location]
text
text that requires a footnote. link:#footnote2[(2)]
== Third Topic
text
== Footnotes
[#footnote1]
link:#footnote1-location[(1)]: footnote 1 text
[#footnote2]
link:#footnote2-location[(2)]: footnote 2 text
----
== Guide
The contents of the guide should be enough to get a new user up and running with your library.
=== Guide Template
[source,asciidoc]
----
== Guide to <LibraryName>
Intro text
=== Basic Tutorials and Examples
Add simple tutorials and/or examples.
=== How to Compile and Link
text
=== How to Test and Debug
text
----
== Reference
Provide a complete API reference to your library, without duplicating the contents of the <<Configuration>> or <<Definitions>> sections, which follow.
=== Reference Template
[source,asciidoc]
----
== Introduction
Introductory text
== Macros
=== Macro1
=== Macro2
== Values
=== Value1
=== Value2
== Types
=== Type1
=== Type2
== Classes
=== Class `class name`
class overview text
==== Class `class name` synopsis
....
namespace boost
{
class <class name>
{
};
};
....
==== Class `class name` constructors and destructor
....
constructor
....
*Requires:* text
*Effects:* text
*Post-conditions:* text
*Returns:* text
*Throws:* text
*Complexity:* text
*Note:* text
*Danger:* text
*Rationale:* text
....
destructor
....
*Requires:* text
*Effects:* text
*Post-conditions:* text
*Returns:* text
*Throws:* text
*Complexity:* text
*Note:* text
*Danger:* text
*Rationale:* text
==== Class `class name` comparison functions
....
comparison-function
....
*Requires:* text
*Effects:* text
*Post-conditions:* text
*Returns:* text
*Throws:* text
*Complexity:* text
*Note:* text
*Danger:* text
*Rationale:* text
==== Class `class name` modifier functions
....
modifier-function
....
*Requires:* text
*Effects:* text
*Post-conditions:* text
*Returns:* text
*Throws:* text
*Complexity:* text
*Note:* text
*Danger:* text
*Rationale:* text
==== Class `class name` observer functions
....
observer-function
....
*Requires:* text
*Effects:* text
*Post-conditions:* text
*Returns:* text
*Throws:* text
*Complexity:* text
*Note:* text
*Danger:* text
*Rationale:* text
==== Class `class name` static functions
....
static-function
....
*Requires:* text
*Effects:* text
*Post-conditions:* text
*Returns:* text
*Throws:* text
*Complexity:* text
*Note:* text
*Danger:* text
*Rationale:* text
== Functions
....
function1
....
*Requires:* text
*Effects:* text
*Post-conditions:* text
*Returns:* text
*Throws:* text
*Complexity:* text
*Note:* text
*Danger:* text
*Rationale:* text
== Objects
== Object specifications
== Examples
----
If your documentation is defined as an Antora component, the `@cppalliance/antora-cpp-reference-extension` extension can be used to generate the reference documentation from the source code.
Refer to xref:docs/antora.adoc[] for more details.
== Configuration
Describe the configuration macros that are used in your library.
=== Configuration Template
[source,asciidoc]
----
== `<LibraryName>` Configuration
== Introduction
`<LibraryName>` uses several configuration macros in
http://www.boost.org/libs/config/config.htm[<boost/config.hpp>], as well as configuration macros meant to be supplied by the application. These macros are documented here.
== Application Defined Macros
These are the macros that may be defined by an application using `<LibraryName>`.
[cols="1,2",options="header",stripes=even,frame=none]
|===
| *Macro* | *Meaning*
|`macro` |meaning text
|`macro` |meaning text
|===
== Public Library Defined Macros
These macros are defined by `<LibraryName>`, but are also expected to be used by application code.
[cols="1,2",options="header",stripes=even,frame=none]
|===
| *Macro* | *Meaning*
|`macro` |meaning text
|`macro` |meaning text
|===
== Library Defined Implementation Macros
These macros are defined by `<LibraryName>` and are implementation details of interest only to implementers.
[cols="1,2",options="header",stripes=even,frame=none]
|===
| *Macro* | *Meaning*
|`macro` |meaning text
|`macro` |meaning text
|===
----
Example:: *Application Defined Macros*
+
These are the macros that may be defined by an application using `<LibraryName>`, for example:
+
[cols="1,2",options="header",stripes=even,frame=none]
|===
| *Macro* | *Meaning*
|`add(x,y)` | The x and y values are added together.
|`mult(x,y)` | The x and Y values are multiplied together.
|===
== Definitions
If your library uses any terminology that might benefit from a description, consider adding a "Definitions" page to your documentation.
Each definition is typically preceded by an anchor, so can be linked to from any other section of your documentation.
This can help reduce duplication of explanations: link to your definitions rather than repeat explanations.
=== Definitions Template
[source,asciidoc]
----
== <LibraryName> Definitions
Introductory text.
== Definitions
[#definition-term1]
*Term1*::
definition-text1
[#definition-term2]
*Term2*::
definition-text2
----
Example:: Assume there is a String-Container library, and that String container algorithms work using some pre-defined concepts:
+
[#Finder Concept]
*Finder Concept*::
A Finder is a function which searches for an arbitrary part of a container.
For example (add example logic here).
+
[#Formatter Concept]
*Formatter Concept*::
Formatters are used by string replace algorithms.
For example (add example logic here).
== Advanced Topics
Advanced topics include advanced tutorials or examples, and also cover porting, customization, synchronization, and performance tuning.
=== Advanced Topics Template
[source,asciidoc]
----
== Advanced Use of <LibraryName>
Intro text
=== Porting Guide
text
=== Customization
text
=== Synchronization
text
=== Performance Tuning
text
=== Complex Examples
text
=== Troubleshooting
text
----
== Frequently Asked Questions (FAQs)
A Frequently Asked Questions (FAQ) section might add value to your documentation, by aiding developers with answers to known issues or complexities.
If there are a large number of questions and answers, group them into sections with headings such as *Errors and Exceptions*, *Performance*, and so on.
Note that every question is in bold, and always ends with a question mark.
=== FAQ Template
[source,asciidoc]
----
=== FAQ
==== *question1?*
answer1
==== *question2?*
answer2
----
Example::
+
*Does this library work with COM methods?*
+
Yes, if you add `#define BOOST_ENABLE_STDCALL` to your code.
+
*Does this library support Windows earlier than Windows 10?*
+
No, the only supported versions of Windows supported are 10 and 11.
== Versioning and Release Notes
Make sure to version your library correctly, and provide release notes for each release.
Refer to xref:version-control.adoc[] and xref:release-notes.adoc[] for details.
== Bibliography
If bibliographic references are required in your documentation for your library, add a bibliography to the documentation.
The book title can be text, or can be a link to a site too if the text of the book is available online.
The ISBN number can be replaced by another reference number if the reference is to an academic paper, or other reference that is not published in book form.
Ideally, list the bibliography in alphabetical order.
=== Bibliography Template
[source,asciidoc]
----
=== Bibliography
[Surname/s] Authors full names. _Book title_. ISBN number, Publication date.
[Surname/s] Authors full names. _Book title_. ISBN number, Publication date.
----
Example:: [Turcan, Wasson] Peter Turcan, Mike Wasson. _Fundamentals of Audio and Video Programming for Games_.
ISBN: 073561945X, 2003.
== Acknowledgements
If acknowledgements are required for your library, add an acknowledgements section to the documentation.
As a rule of thumb, the acknowledgements should be ordered with the most important contributions coming first.
Links can be included, if required.
=== Acknowledgements Template
[source,asciidoc]
----
=== Acknowledgements
The author appreciates the contributions to the library made by the following:
* text1
* text2
----
Example:: The author appreciates the contributions to the library made by the following:
+
[disc]
* John Doe and Jane Doe for editing the original draft documentation.
* John Doe for input on the architecture and design of the API interfaces.
* Jane Doe for numerous improvements and suggestions on the text of the error messages.
== Other Appendices
If any other appendices are needed, add them here.
== See Also
* xref:docs/asciidoc.adoc[]
* xref:site-docs-style-guide.adoc[]
_Revised April, 2023_
_Distributed under the Boost Software License, Version 1.0. Refer to http://www.boost.org/LICENSE_1_0.txt_.
Reference in New Issue View Git Blame Copy Permalink