=========================== Crate ``sphinx_rustdocgen`` =========================== .. rust:crate:: sphinx_rustdocgen :index: 0 Library for the sphinx-rustdocgen executable. It consists of functions to extract content from the AST and to write the content to an RST or MD file. The crate is tested on itself, so all the documentation in the crate is in RST. The tests for Markdown are done on the dependencies. .. rubric:: Modules .. toctree:: :maxdepth: 1 directives formats nodes utils .. rust:use:: sphinx_rustdocgen :used_name: self .. rust:use:: sphinx_rustdocgen :used_name: crate .. rust:use:: std::fs::File :used_name: File .. rust:use:: std::fs::create_dir_all :used_name: create_dir_all .. rust:use:: std::io::Write :used_name: Write .. rust:use:: std::path::Path :used_name: Path .. rust:use:: std::path::PathBuf :used_name: PathBuf .. rust:use:: serde::Deserialize :used_name: Deserialize .. rust:use:: sphinx_rustdocgen::directives::CrateDirective :used_name: CrateDirective .. rust:use:: sphinx_rustdocgen::directives::DirectiveVisibility :used_name: DirectiveVisibility .. rust:use:: sphinx_rustdocgen::directives::ExecutableDirective :used_name: ExecutableDirective .. rust:use:: sphinx_rustdocgen::formats::Format :used_name: Format .. rust:use:: sphinx_rustdocgen::utils::FileTopLevelDirective :used_name: FileTopLevelDirective .. rust:use:: sphinx_rustdocgen::utils::SourceCodeFile :used_name: SourceCodeFile :reexport: sphinx_rustdocgen .. rust:use:: sphinx_rustdocgen::utils::check_for_manifest :used_name: check_for_manifest :reexport: sphinx_rustdocgen .. rubric:: Re-exports * :rust:any:`sphinx_rustdocgen::utils::SourceCodeFile` * :rust:any:`sphinx_rustdocgen::utils::check_for_manifest` .. rubric:: Functions .. rust:function:: sphinx_rustdocgen::traverse_crate :index: 0 :vis: pub :layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"traverse_crate"},{"type":"punctuation","value":"("},{"type":"name","value":"config"},{"type":"punctuation","value":": "},{"type":"link","value":"Configuration","target":"Configuration"},{"type":"punctuation","value":")"}] Traverse the crate and extract the docstrings for the items. Args: :config: The configuration for the crate. .. rubric:: Structs and Unions .. rust:struct:: sphinx_rustdocgen::Configuration :index: 1 :vis: pub :toc: struct Configuration :layout: [{"type":"keyword","value":"struct"},{"type":"space"},{"type":"name","value":"Configuration"}] Struct to hold the deserialized configuration passed from Python. .. rust:variable:: sphinx_rustdocgen::Configuration::crate_name :index: 2 :vis: pvt :toc: crate_name :layout: [{"type":"name","value":"crate_name"},{"type":"punctuation","value":": "},{"type":"link","value":"String","target":"String"}] The name of the crate. .. rust:variable:: sphinx_rustdocgen::Configuration::crate_dir :index: 2 :vis: pvt :toc: crate_dir :layout: [{"type":"name","value":"crate_dir"},{"type":"punctuation","value":": "},{"type":"link","value":"PathBuf","target":"PathBuf"}] The directory containing the Cargo.toml file for the crate. .. rust:variable:: sphinx_rustdocgen::Configuration::doc_dir :index: 2 :vis: pvt :toc: doc_dir :layout: [{"type":"name","value":"doc_dir"},{"type":"punctuation","value":": "},{"type":"link","value":"PathBuf","target":"PathBuf"}] The directory under which to create the crate's documentation. A new directory is created under this directory for the crate. .. rust:variable:: sphinx_rustdocgen::Configuration::force :index: 2 :vis: pvt :toc: force :layout: [{"type":"name","value":"force"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"}] Rebuild document for all files, even if it has not changed. .. rust:variable:: sphinx_rustdocgen::Configuration::format :index: 2 :vis: pvt :toc: format :layout: [{"type":"name","value":"format"},{"type":"punctuation","value":": "},{"type":"link","value":"Format","target":"Format"}] The format to use for the output. .. rust:variable:: sphinx_rustdocgen::Configuration::visibility :index: 2 :vis: pvt :toc: visibility :layout: [{"type":"name","value":"visibility"},{"type":"punctuation","value":": "},{"type":"link","value":"DirectiveVisibility","target":"DirectiveVisibility"}] The required visibility of the items to include. .. rust:variable:: sphinx_rustdocgen::Configuration::strip_src :index: 2 :vis: pvt :toc: strip_src :layout: [{"type":"name","value":"strip_src"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"}] Whether to remove the src/ directory when generating the docs or not. .. rubric:: Implementations .. rust:impl:: sphinx_rustdocgen::Configuration :index: -1 :vis: pub :layout: [{"type":"keyword","value":"impl"},{"type":"space"},{"type":"link","value":"Configuration","target":"Configuration"}] :toc: impl Configuration .. rubric:: Functions .. rust:function:: sphinx_rustdocgen::Configuration::get_canonical_crate_dir :index: -1 :vis: pvt :layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"get_canonical_crate_dir"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"PathBuf","target":"PathBuf"}] Canonicalize the crate directory and return it. .. rust:struct:: sphinx_rustdocgen::RuntimeConfiguration :index: 1 :vis: crate :toc: struct RuntimeConfiguration :layout: [{"type":"keyword","value":"struct"},{"type":"space"},{"type":"name","value":"RuntimeConfiguration"}] Runtime version of the configuration after validation and normalizing. .. rust:variable:: sphinx_rustdocgen::RuntimeConfiguration::crate_name :index: 2 :vis: pvt :toc: crate_name :layout: [{"type":"name","value":"crate_name"},{"type":"punctuation","value":": "},{"type":"link","value":"String","target":"String"}] The name of the crate in the configuration. .. rust:variable:: sphinx_rustdocgen::RuntimeConfiguration::crate_dir :index: 2 :vis: pvt :toc: crate_dir :layout: [{"type":"name","value":"crate_dir"},{"type":"punctuation","value":": "},{"type":"link","value":"PathBuf","target":"PathBuf"}] The crate's root directory, the one which contains ``Cargo.toml``. .. rust:variable:: sphinx_rustdocgen::RuntimeConfiguration::src_dir :index: 2 :vis: pvt :toc: src_dir :layout: [{"type":"name","value":"src_dir"},{"type":"punctuation","value":": "},{"type":"link","value":"Option","target":"Option"},{"type":"punctuation","value":"<"},{"type":"link","value":"PathBuf","target":"PathBuf"},{"type":"punctuation","value":">"}] The crate's src/ directory, if one is found and ``strip_src`` is true. .. rust:variable:: sphinx_rustdocgen::RuntimeConfiguration::doc_dir :index: 2 :vis: pvt :toc: doc_dir :layout: [{"type":"name","value":"doc_dir"},{"type":"punctuation","value":": "},{"type":"link","value":"PathBuf","target":"PathBuf"}] The directory under which to write the documents. .. rust:variable:: sphinx_rustdocgen::RuntimeConfiguration::force :index: 2 :vis: pvt :toc: force :layout: [{"type":"name","value":"force"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"}] Whether to rewrite all the documents, even the ones that are unchanged. .. rust:variable:: sphinx_rustdocgen::RuntimeConfiguration::format :index: 2 :vis: pvt :toc: format :layout: [{"type":"name","value":"format"},{"type":"punctuation","value":": "},{"type":"link","value":"Format","target":"Format"}] The format of the docstrings. .. rust:variable:: sphinx_rustdocgen::RuntimeConfiguration::max_visibility :index: 2 :vis: pvt :toc: max_visibility :layout: [{"type":"name","value":"max_visibility"},{"type":"punctuation","value":": "},{"type":"link","value":"DirectiveVisibility","target":"DirectiveVisibility"}] Only document items with visibility less than this. .. rust:variable:: sphinx_rustdocgen::RuntimeConfiguration::executables :index: 2 :vis: pvt :toc: executables :layout: [{"type":"name","value":"executables"},{"type":"punctuation","value":": "},{"type":"link","value":"Vec","target":"Vec"},{"type":"punctuation","value":"<"},{"type":"link","value":"SourceCodeFile","target":"SourceCodeFile"},{"type":"punctuation","value":">"}] The executables within the crate that will be documented. .. rust:variable:: sphinx_rustdocgen::RuntimeConfiguration::lib :index: 2 :vis: pvt :toc: lib :layout: [{"type":"name","value":"lib"},{"type":"punctuation","value":": "},{"type":"link","value":"Option","target":"Option"},{"type":"punctuation","value":"<"},{"type":"link","value":"SourceCodeFile","target":"SourceCodeFile"},{"type":"punctuation","value":">"}] The crate's library to document, if any. .. rubric:: Implementations .. rust:impl:: sphinx_rustdocgen::RuntimeConfiguration :index: -1 :vis: crate :layout: [{"type":"keyword","value":"impl"},{"type":"space"},{"type":"link","value":"RuntimeConfiguration","target":"RuntimeConfiguration"}] :toc: impl RuntimeConfiguration .. rubric:: Functions .. rust:function:: sphinx_rustdocgen::RuntimeConfiguration::get_doc_file_name :index: -1 :vis: crate :layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"get_doc_file_name"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"source_file_path"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"link","value":"Path","target":"Path"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"PathBuf","target":"PathBuf"}] Returns the stem of the document file relative to the top level directory .. rust:function:: sphinx_rustdocgen::RuntimeConfiguration::write_doc_file :index: -1 :vis: pvt :layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"write_doc_file"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"source_file_path"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"link","value":"Path","target":"Path"},{"type":"punctuation","value":", "},{"type":"name","value":"file_top_level_directive"},{"type":"punctuation","value":": "},{"type":"keyword","value":"impl"},{"type":"space"},{"type":"link","value":"FileTopLevelDirective","target":"FileTopLevelDirective"},{"type":"punctuation","value":")"}] Write a documentation file for the provided source file path and content. Args: :source_file_path: The path of the source file corresponding to the content. :content_fn: A function to extract the content for the file. .. rubric:: Traits implemented .. rust:impl:: sphinx_rustdocgen::RuntimeConfiguration::From :index: -1 :vis: crate :layout: [{"type":"keyword","value":"impl"},{"type":"space"},{"type":"link","value":"From","target":"From"},{"type":"punctuation","value":"<"},{"type":"link","value":"Configuration","target":"Configuration"},{"type":"punctuation","value":">"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"RuntimeConfiguration","target":"RuntimeConfiguration"}] :toc: impl From for RuntimeConfiguration .. rubric:: Functions .. rust:function:: sphinx_rustdocgen::RuntimeConfiguration::From::from :index: -1 :vis: pvt :layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"from"},{"type":"punctuation","value":"("},{"type":"name","value":"config"},{"type":"punctuation","value":": "},{"type":"link","value":"Configuration","target":"Configuration"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Self","target":"Self"}] Create a validated and normalized version of the :rust:struct:`Configuration`.