diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index d1c3d5cf9..fc6eac0a3 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -273,6 +273,10 @@ navigation: - page: GraphQL Reference path: ./pages/api-references/generate-graphql-ref.mdx slug: generate-graphql-ref + - page: Library documentation + path: ./pages/api-references/generate-library-docs.mdx + slug: generate-library-docs + hidden: true - section: Customization skip-slug: true contents: diff --git a/fern/products/docs/pages/api-references/generate-library-docs.mdx b/fern/products/docs/pages/api-references/generate-library-docs.mdx new file mode 100644 index 000000000..42182a9d6 --- /dev/null +++ b/fern/products/docs/pages/api-references/generate-library-docs.mdx @@ -0,0 +1,183 @@ +--- +title: Generate library documentation +description: Use Fern Docs to generate documentation for Python and C++ libraries. This beta feature renders classes, methods, and types as an interactive reference. +availability: beta +--- + + + + + Library documentation generation is in beta. The feature and its configuration are subject to change. + + +Fern generates library documentation from Python and C++ source code. Point Fern at a Git repository containing your library, and Fern renders classes, methods, types, and modules as an interactive reference. + +## Supported languages + +| Language | Source format | Status | +|----------|--------------|--------| +| Python | `.py` files with docstrings | Beta | +| C++ | Header files (`.h`, `.hpp`) with Doxygen-style comments | Beta | + +## Configuration + +Configure library documentation in your `docs.yml` file using the `libraries` key. + +```yaml title="docs.yml" +libraries: + my-lib: + input: + git: "https://github.com/org/repo" + subpath: "src/sdk" # optional + output: + path: "./pages/reference" + lang: python +``` + +### Configuration properties + + + The language of the library. Supported values: `python`, `cpp`. Routes to the appropriate documentation generator. + + + + The Git repository URL containing the library source code. Only `git` input is supported. + + + + A subdirectory within the repository to use as the root of the library. For example, `"src/sdk"` if the library code lives in a subdirectory. + + + + The local path where Fern outputs the generated reference pages. + + + + Path to a [Doxyfile](https://www.doxygen.nl/manual/config.html) configuration file. C++ only. The file is read from disk and sent as raw content to the backend. + + +## Examples + + + + +```yaml title="docs.yml" +libraries: + plant-sdk: + input: + git: "https://github.com/my-org/plant-sdk" + subpath: "src/plant" + output: + path: "./pages/plant-reference" + lang: python +``` + + + + +```yaml title="docs.yml" +libraries: + plant-sdk: + input: + git: "https://github.com/my-org/plant-sdk" + subpath: "include" + output: + path: "./pages/plant-reference" + lang: cpp + config: + doxyfile: "./Doxyfile.txt" +``` + + + + +### Multiple libraries + +To generate documentation for more than one library, add multiple entries under the `libraries` key: + +```yaml title="docs.yml" +libraries: + plant-sdk: + input: + git: "https://github.com/my-org/plant-sdk" + output: + path: "./pages/plant-reference" + lang: python + garden-sdk: + input: + git: "https://github.com/my-org/garden-sdk" + subpath: "include" + output: + path: "./pages/garden-reference" + lang: cpp + config: + doxyfile: "./Doxyfile.txt" +``` + +## Generate your library docs + +After configuring `docs.yml`, run the following command to generate and preview your documentation: + +```bash +fern docs dev +``` + +This starts a local development server at `http://localhost:3000` where you can view the generated library reference. + +To publish your documentation, run: + +```bash +fern generate --docs +``` + +## Writing effective source comments + +Fern uses comments in your source code to generate descriptions for classes, methods, and types. + + + + +Use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) for the best results: + +```python +class PlantClient: + """Client for interacting with the Plant API. + + Args: + api_key: Your API key for authentication. + base_url: The base URL of the Plant API. + """ + + def get_plant(self, plant_id: str) -> Plant: + """Retrieve a plant by its ID. + + Args: + plant_id: The unique identifier of the plant. + + Returns: + The requested Plant object. + """ +``` + + + + +Use [Doxygen-style comments](https://www.doxygen.nl/manual/docblocks.html) for the best results: + +```cpp +/** + * @brief Client for interacting with the Plant API. + */ +class PlantClient { +public: + /** + * @brief Retrieve a plant by its ID. + * @param plantId The unique identifier of the plant. + * @return The requested Plant object. + */ + Plant getPlant(const std::string& plantId); +}; +``` + + +