Merge pull request #450 from NikitaZotov/feat/improve_docs_headers

[docs] Unify docs header namings
ostis-ai · Dec 17, 2024 · 5ec2d77 · 5ec2d77
2 parents 188c5dc + c7c4ad9
commit 5ec2d77
Show file tree

Hide file tree

Showing 16 changed files with 60 additions and 54 deletions.
diff --git a/docs/build/build_system.md b/docs/build/build_system.md
@@ -1,4 +1,4 @@
-# Build system
+# Build System
 
 ## Implementation details
 

diff --git a/docs/build/quick_start.md b/docs/build/quick_start.md
@@ -1,4 +1,4 @@
-# Quick start
+# Quick Start for Developers
 
 This guide provides short information for developers to start to work with sc-machine quickly. You can always learn more about the sc-machine's [build system](build_system.md).
 

diff --git a/docs/dev/codestyle.md b/docs/dev/codestyle.md
@@ -1,11 +1,11 @@
+# Code Style Guide
+
 In general, [Google's coding standard](https://google.github.io/styleguide/cppguide.html) is used, and we strongly 
 encourage to read it.
 
-## Code Style Guide
-
 All code should conform to C++17 standard. Here's a summary of the key rules specified in the configuration:
 
-### Includes
+## Includes
 
 * We use `.cpp` and `.hpp` files, not `.cc` and `.h` (`.c` and `.h` are used for C code), in UTF-8 encoding.
 * File names are lowercase with underscores, like `sc_memory.cpp`.
@@ -37,7 +37,7 @@ libraries. External libraries have the highest priority.
 !!! note
     Unfortunately, sources of `sc-kpm` does not comply these rules. But you must comply these rules!
 
-### Indentation and Spacing
+## Indentation and Spacing
 
 * The code should use spaces for indentation. The indentation width is set to 2 spaces. The code should not use tabs.
 
@@ -162,7 +162,7 @@ sc_uint32& ref = x;
 ScAddr const & addr; // reference to the const `ScAddr`.
 ```
 
-### Whitespace
+## Whitespace
 
 * Remove extra whitespaces at the end of lines.
 * Spaces in empty blocks and parentheses should be omitted.
@@ -177,7 +177,7 @@ std::vector<sc_uint32> numbers = {
 };
 ```
 
-### Brace Style
+## Brace Style
 
 * Braces for functions, classes, namespaces, etc., should be on a new line.
 
@@ -277,7 +277,7 @@ sc_uint32 ExampleFunction(
     sc_uint32 * result, sc_uint32 * delta)
 ```
 
-### Line Length and Wrapping
+## Line Length and Wrapping
 
 * The maximum column limit is set to 120 characters.
 
@@ -346,22 +346,22 @@ for (ScAddr const & addr : addrList)
 }
 ```
 
-### Naming
+## Naming
 
-#### C Naming
+### C Naming
 
 * Macros and C-style enums must be named in UPPER_CASE, and enum values must be prefixed with a capitalized enum name.
 * All other objects must be named in snake_case.
 
-#### C++ Naming
+### C++ Naming
 
 * Underscores are allowed only in prefixes for member variables and namespace names, like `int m_keynodeAddr; namespace sc_utils`.
 * We use `using` keyword instead of `typedef`.
 * Compile-time constants must be named in camelCase, starting with a lower-case `k`, e.g. `kCompileTimeConstant` 
 and marked as `constexpr` when possible.
 * Values of enum classes must be named in CamelCase, e.g. `enum class Color { Red, Green, LightBlue };`.
 
-### Comments
+## Comments
 
 * Doxygen-style comments can be used.
 

diff --git a/docs/index.md b/docs/index.md
@@ -8,46 +8,46 @@ At its core, sc-machine operates as a **graph database management system**, enab
 
 Table of contents:
 
-- [Quick start](quick_start.md) - *get up and running with sc-machine quickly*
+- [Quick Start](quick_start.md) - *get up and running with sc-machine quickly*
 - [Docker](docker.md) - *get up and running with sc-machine in docker*
-- **User guides** - *detailed instructions on implementing agents*
+- **User Guides** - *detailed instructions on implementing agents*
     * C++ Guides - *guidelines for implementing agents on C++*
-        * [C++ Simple guide for implementing agent](sc-memory/api/cpp/guides/simple_guide_for_implementing_agent.md)
-    * [Migrate to new agent API](sc-tools/migrate_to_new_agent_api.md) - *description of script that can be used to migrate to new C++ Agents API*
+        * [C++ Simple Guide for Implementing Agent](sc-memory/api/cpp/guides/simple_guide_for_implementing_agent.md)
+    * [Migrate to New Agent API](sc-tools/migrate_to_new_agent_api.md) - *description of script that can be used to migrate to new C++ Agents API*
 - **API** - *comprehensive documentation for C++, Python, and TypeScript APIs*
     * C++ API - *detailed guides on using the core and extended APIs for interacting with sc-memory*
         * [C++ Core API](sc-memory/api/cpp/core/api.md) - *documentation of C++ core API for creating, retrieving and erasing sc-elements in sc-memory*
         * C++ Extended API - *documentation of C++ extended API for manipulating with system identifiers of sc-elements and sc-templates*
-            * [C++ System identifier API](sc-memory/api/cpp/extended/helper_api.md) - *documentation of C++ extended API for manipulating with system identifiers of sc-elements*
+            * [C++ System Identifier API](sc-memory/api/cpp/extended/helper_api.md) - *documentation of C++ extended API for manipulating with system identifiers of sc-elements*
             * [C++ ScTemplate API](sc-memory/api/cpp/extended/template_api.md) - *documentation of C++ extended API for creating and retrieving graphs (it is very useful when you want to work big sc-constructions)* 
             * C++ Agents API - *documentation of C++ Agents API for creating agents*
                 * [C++ Events API](sc-memory/api/cpp/extended/agents/events.md) - *enables developers to create and manage events within the sc-machine, allowing agents to respond dynamically to various triggers*
-                * [C++ Event subscriptions API](sc-memory/api/cpp/extended/agents/event_subscriptions.md) - *details how agents can subscribe to specific events and receive notifications when those events occur*
+                * [C++ Event Subscriptions API](sc-memory/api/cpp/extended/agents/event_subscriptions.md) - *details how agents can subscribe to specific events and receive notifications when those events occur*
                 * [C++ Waiters API](sc-memory/api/cpp/extended/agents/waiters.md) - *allows developers to implement wait conditions that pause agent execution until specified conditions are met or events are triggered*
                 * [C++ Keynodes API](sc-memory/api/cpp/extended/agents/keynodes.md) - *provides functionality for creating, retrieving, and manipulating keynodes, which represent significant concepts within the knowledge graph*
                 * [C++ Actions API](sc-memory/api/cpp/extended/agents/actions.md) - *outlines how to define and initiate actions that agents can perform, detailing their arguments and results*
                 * [C++ Agents API](sc-memory/api/cpp/extended/agents/agents.md) - *focuses on agent creation and management*
-                * [C++ Agent context API](sc-memory/api/cpp/extended/agents/agent_context.md) - *explains how to manage the context in which agents operate*
+                * [C++ Agent Context API](sc-memory/api/cpp/extended/agents/agent_context.md) - *explains how to manage the context in which agents operate*
                 * [C++ Modules API](sc-memory/api/cpp/extended/agents/modules.md) - *describes how to register agents in an application*
     * Python API - *documentation on using the Python client for interacting with sc-memory*
         * [Python Core API](https://github.com/ostis-ai/py-sc-client) - *documentation of Python core API for creating, retrieving and erasing sc-elements and sc-events in sc-memory*
         * [Python Extended API](https://github.com/ostis-ai/py-sc-kpm) - *documentation of Python extended API for manipulating with large graphs*
     * TypeScript API - *documentation on using the TypeScript client for interacting with sc-memory*
         * [TypeScript Core API](https://github.com/ostis-ai/ts-sc-client) - *documentation of TypeScript core API for creating, retrieving and erasing sc-elements and sc-events in sc-memory*
-    * [sc-element types](scs/sc_element_types.md) - *detailed description of supported element types*
+    * [sc-element Types](scs/sc_element_types.md) - *detailed description of supported element types*
     * [SCs-code](scs/scs.md) - *documentation on SCs Language with examples*
 - **Tools** - *information on various tools that enhance your experience with sc-machine*
-    * [Knowledge Base builder](sc-tools/sc_builder.md) - *description of options of sc-builder for knowledge base sources*
-    * [Knowledge Base repo file](sc-tools/kb_repo_file.md) - *description of configuration of knowledge base sources*
+    * [Knowledge Base Builder](sc-tools/sc_builder.md) - *description of options of sc-builder for knowledge base sources*
+    * [Knowledge Base Repo File](sc-tools/kb_repo_file.md) - *description of configuration of knowledge base sources*
     * [sc-machine Runner](sc-tools/sc_machine.md) - *description of options of sc-machine runner*
-- **Build instructions** - *guidelines for building the project, configuring settings*
-    * [Quick start](build/quick_start.md) - *get up and start developing sc-machine quickly*
-    * [Build system](build/build_system.md) - *how to build the project and use it as a library*
+- **Build Instructions** - *guidelines for building the project, configuring settings*
+    * [Quick Start for Developers](build/quick_start.md) - *get up and start developing sc-machine quickly*
+    * [Build System](build/build_system.md) - *how to build the project and use it as a library*
     * [CMake Flags](build/cmake_flags.md) - *description of CMake flags used to configure sc-machine*
     * [Configuration File](build/config.md) - *description of a configuration file of sc-machine*
 - **Development** - *guidelines for contributing to development*
     * [Contributing Guide](https://github.com/ostis-ai/sc-machine/blob/main/CONTRIBUTING.md) - *guide for those who wants to make contribution into sc-machine*
-    * [Codestyle Guide](dev/codestyle.md) - *guide for those who wants to write code for sc-machine*
+    * [Code Style Guide](dev/codestyle.md) - *guide for those who wants to write code for sc-machine*
     * [Dev Container](dev/devcontainer.md) - *guide for those who wants to develop sc-machine via docker*
 - [License](https://github.com/ostis-ai/sc-machine/blob/main/COPYING.MIT)
 - [Changelog](changelog.md)
diff --git a/docs/quick_start.md b/docs/quick_start.md
@@ -1,4 +1,4 @@
-# Quick start
+# Quick Start
 
 ## Use sc-machine as a C++ library in your project
 

diff --git a/docs/sc-memory/api/cpp/extended/agents/agent_context.md b/docs/sc-memory/api/cpp/extended/agents/agent_context.md
@@ -1,4 +1,4 @@
-# **C++ Agent context API**
+# **C++ Agent Context API**
 
 !!! note
     This documentation is correct for only versions of sc-machine that >= 0.10.0.

diff --git a/docs/sc-memory/api/cpp/extended/agents/event_subscriptions.md b/docs/sc-memory/api/cpp/extended/agents/event_subscriptions.md
@@ -1,4 +1,4 @@
-# **ScEventSubscription API**
+# **C++ Event Subscriptions API**
 
 !!! note
     This is correct for only versions of sc-machine that >= 0.10.0.

diff --git a/docs/sc-memory/api/cpp/extended/agents/events.md b/docs/sc-memory/api/cpp/extended/agents/events.md
@@ -1,4 +1,4 @@
-# **ScEvent API**
+# **C++ Events API**
 
 !!! note
     This is correct for only versions of sc-machine that >= 0.10.0.

diff --git a/docs/sc-memory/api/cpp/extended/helper_api.md b/docs/sc-memory/api/cpp/extended/helper_api.md
@@ -1,4 +1,4 @@
-# **ScHelper API**
+# **C++ System Identifier API**
 
 !!! note
     This is correct for only versions of sc-machine that >= 0.10.0.
@@ -173,7 +173,8 @@ If you want to resolve quintuple sc-element with its system identifier you can p
 ...
 ScSystemIdentifierQuintuple quintuple;
 bool const & isSystemIdentifierResolved 
-    = context.ResolveElementSystemIdentifier("my_node", ScType::ConstNode, quintuple);
+    = context.ResolveElementSystemIdentifier(
+        "my_node", ScType::ConstNode, quintuple);
 ScAddr const & myNodeAddr = quintuple.addr1;
 // The sc-address of resolved sc-node by provided system identifier.
 ScAddr const & arcToSystemIdtfLinkAddr = quintuple.addr2;

diff --git a/docs/sc-memory/api/cpp/extended/template_api.md b/docs/sc-memory/api/cpp/extended/template_api.md
@@ -1,4 +1,4 @@
-# **ScTemplate API**
+# **C++ ScTemplate API**
 
 !!! warning 
     This documentation is correct for only versions of sc-machine that >= 0.10.0.

diff --git a/docs/sc-memory/api/cpp/guides/simple_guide_for_implementing_agent.md b/docs/sc-memory/api/cpp/guides/simple_guide_for_implementing_agent.md
@@ -1,4 +1,4 @@
-# **Implementing agent in C++**
+# **C++ Simple Guide for Implementing Agent**
 
 !!! note
     This is correct for only versions of sc-machine that >= 0.10.0.

diff --git a/docs/sc-tools/kb_repo_file.md b/docs/sc-tools/kb_repo_file.md
@@ -1,6 +1,11 @@
+# **Knowledge Base Repo File**
+
 ## Knowledge base repository file - repo.path
+
 For more complex KB setups (with several folders across the filesystem, for example), we've created an internal file format called `repo.path`. It allows you to specify all the folders that should be built into the KB or exclude some files or subfolders.
-### Example
+
+## Example
+
 ```sh
 # Comments should start with hashtag as a first character in the line
 # Here you can specify path to one or several kb folders

diff --git a/docs/sc-tools/migrate_to_new_agent_api.md b/docs/sc-tools/migrate_to_new_agent_api.md
@@ -1,4 +1,4 @@
-# Migrate to new agent api
+# **Migrate to New Agent API**
 
 This is a program that translates sc-machine usage from old API into new API.
 

diff --git a/docs/sc-tools/sc_builder.md b/docs/sc-tools/sc_builder.md
@@ -1,4 +1,4 @@
-# sc-builder
+# **Knowledge Base Builder**
 
 Sc-builder tool allows to translate knowledge base sources into binaries. You can find it in a `/build/<Release|Debug>/bin` directory.
 

diff --git a/docs/sc-tools/sc_machine.md b/docs/sc-tools/sc_machine.md
@@ -1,4 +1,4 @@
-# sc-machine
+# **sc-machine Runner**
 
 !!! note
     This is correct for only versions of sc-machine that >= 0.10.0.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,46 +8,46 @@ extra_javascript:
 
 nav:
   - Home: index.md
-  - Quick start: quick_start.md
+  - Quick Start: quick_start.md
   - Docker: docker.md
-  - User guides:
+  - User Guides:
       - C++ Guides:
-          - C++ Simple guide for implementing agent: sc-memory/api/cpp/guides/simple_guide_for_implementing_agent.md
-      - Migrate to new agent API: sc-tools/migrate_to_new_agent_api.md
+          - C++ Simple Guide for Implementing Agent: sc-memory/api/cpp/guides/simple_guide_for_implementing_agent.md
+      - Migrate to New Agent API: sc-tools/migrate_to_new_agent_api.md
   - API:
       - C++ API:
           - C++ Core API: sc-memory/api/cpp/core/api.md
           - C++ Extended API:
-              - C++ System identifier API: sc-memory/api/cpp/extended/helper_api.md
+              - C++ System Identifier API: sc-memory/api/cpp/extended/helper_api.md
               - C++ ScTemplate API: sc-memory/api/cpp/extended/template_api.md
               - C++ Agents API:
                   - C++ Events API: sc-memory/api/cpp/extended/agents/events.md
-                  - C++ Event subscriptions API: sc-memory/api/cpp/extended/agents/event_subscriptions.md
+                  - C++ Event Subscriptions API: sc-memory/api/cpp/extended/agents/event_subscriptions.md
                   - C++ Waiters API: sc-memory/api/cpp/extended/agents/waiters.md
                   - C++ Agents API: sc-memory/api/cpp/extended/agents/agents.md
                   - C++ Keynodes API: sc-memory/api/cpp/extended/agents/keynodes.md
                   - C++ Actions API: sc-memory/api/cpp/extended/agents/actions.md
-                  - C++ Agent context API: sc-memory/api/cpp/extended/agents/agent_context.md
+                  - C++ Agent Context API: sc-memory/api/cpp/extended/agents/agent_context.md
                   - C++ Modules API: sc-memory/api/cpp/extended/agents/modules.md
       - Python API:
           - Python Core API: https://github.com/ostis-ai/py-sc-client
           - Python Extended API: https://github.com/ostis-ai/py-sc-kpm
       - TypeScript API:
           - TypeScript Core API: https://github.com/ostis-ai/ts-sc-client
-      - sc-element types: scs/sc_element_types.md
+      - sc-element Types: scs/sc_element_types.md
       - SCs-code: scs/scs.md
   - Tools:
       - Knowledge Base Builder: sc-tools/sc_builder.md
-      - Knowledge Base repo file: sc-tools/kb_repo_file.md
+      - Knowledge Base Repo File: sc-tools/kb_repo_file.md
       - sc-machine Runner: sc-tools/sc_machine.md
-  - Build instructions:
-      - Quick start: build/quick_start.md
-      - Build system: build/build_system.md
-      - CMake flags: build/cmake_flags.md
-      - Configuration file: build/config.md
+  - Build Instructions:
+      - Quick Start for Developers: build/quick_start.md
+      - Build System: build/build_system.md
+      - CMake Flags: build/cmake_flags.md
+      - Configuration File: build/config.md
   - Development:
       - Contributing Guide: https://github.com/ostis-ai/sc-machine/blob/main/CONTRIBUTING.md
-      - Codestyle Guide: dev/codestyle.md
+      - Code Style Guide: dev/codestyle.md
       - Dev Container: dev/devcontainer.md
   - License: https://github.com/ostis-ai/sc-machine/blob/main/COPYING.MIT
   - Changelog: changelog.md