Package: docinit
DocInitDocInit is an opiniated, yet flexible documentation generator for your Python projects.
It removes the burden of rewriting the same configuration files over and over, and instead favors a simple, non-repetitive declarative style. It usesSphinxandSphinx AutoAPIbehind the scenes.FeaturesEntirely configurable from yoursetup.cfgfileAutomatically fills the blanks so you don’t have to repeat yourselfAllows master and sub projectsCompatible withRead the DocsFlexible and extensibleExampleTheTimeflux documentationis managed by DocInit.Installpip install docinitUsageWrite your documentationOr not. If you don’t do anything, DocInit will automatically find your packages, generate API documentation, and create an index page (using either your repo’sREADME.rstfile or a default paragraph).You can add your own.rstfiles in thedocdirectory, and overwrite the defaultindex.rst. Put your logo and favicon indoc/_static/logo.pnganddoc/_static/favicon.ico, respectively.If you need to configure further, do it in thedocinitsection of yoursetup.cfg. Refer to theConfigurationsection for details.Setup a Sphinx projectThe following will take care of initializing everything:python setup.py docinitIf you don’t have asetup.pyfile, you can instead simply run:docinitDon’t worry, nothing will be overwritten if a file with the same name already exists. There is no need to re-run this command, even if you modify yoursetup.cfg. But if you do, nothing bad will happen.You don’t have to commit the generated files. Refer to theRead the Docssection to learn how to setup your project at build time.Buildcd doc
make htmlYou can now find your generated documentation indoc/_build/html/.By default, themakecommand will return an error (but will still build everything) in case of warning. This allows for easy integration in your CI/CD pipelines.ConfigurationThe following options are accepted:KeyTypedoc_dirstrnamestrparent_urlstrlogo_urlstrfavicon_urlstrversionstrreleasestrpackageslistauthorstrcopyrightstranalyticsstrcanonical_urlstrThere is no required option. If not set, DocInit will try to find an appropriate value elsewhere. If it fails, it will settle on a default value.doc_dirThis is where your documentation lives.DefaultLookupsdocsource-dirin thebuild_sphinxsectionnameThe name of your project.DefaultLookupsProjectprojectin thebuild_sphinxsectionnamein themetadatasectionname of the current git repoparent_urlIf you are managing asubproject, this is the URL of the main project. When set, DocInit adds aBackentry in the menu, and configures theintersphinx mapping.DefaultLookupsNonelogo_urlThe URL of an image that will be downloaded todoc/_static/logo.png. Useful for subprojects.DefaultLookupsNonefavicon_urlThe URL of an image that will be downloaded todoc/_static/favicon.ico. Useful for subprojects.DefaultLookupsNoneversionThesemantic versionof your package. If it is not explicitly defined, DocInit will usesetuptools_scmto fetch it from git tags, or fallback to0.0.0.DefaultLookupsFrom git tagsversionin thebuild_sphinxsectionversionin themetadatasectionreleaseThe full version of your package, including VCS status. If it is not explicitly defined, DocInit will usesetuptools_scmto fetch it from git tags, or fallback to0.0.0.DefaultLookupsFrom git tagsreleasein thebuild_sphinxsectionpackagesThe list of packages for which the API documentation will be generated. If it is not specified, DocInit will discover packages from the root of your project (wheresetup.cfgis located).DefaultLookupsfind:packagesin theoptionssectionauthorThe author of the project.DefaultLookupsAnonymousauthorin themetadatasectionFrom the first commit in the current git repositorycopyrightThe copyright for this project. If it is not defined, it will be constructed from the year of the first commit, the current year, andauthor.DefaultLookupsGeneratedcopyrightin thebuild_sphinxsectionanalyticsYour Google Analytics ID. It should look likeUA-XXXXXXX-1.DefaultLookupsNonecanonical_urlIf your URL is available through multiple URLs, the canonical url indicates to search engines which one it should index. The URL points to the root path of the documentation and requires a trailing slash.DefaultLookupsNoneArbitrary optionsThat is not all: you can pass arbitrary options, and they will be injected inconf.py. For example, setting:autoapi_generate_api_docs = 0will disable API documentation. Please refer to the officialSphinxandSphinx AutoAPIdocumentation for recognized options.Read the docsIf you decide to not push the files created by DocInit, the easiest way is to install your package before building the docs. You can configure this behavior either in theAdvanced settingstab of your dashboard or in yourconfiguration file.Then you just need to invoke DocInit during the setup process.This can be achieved in yoursetup.py:setup(...setup_requires="docinit",docinit=True,...)Or if you prefer, in yourpyproject.toml:[tool.docinit][build-system]requires=["setuptools>=42","wheel","docinit"]build-backend="setuptools.build_meta"Please note: before version20.1.b1and since version20.1.1,pipbuilds in a temporary directory. Therefore, onRead The Docsyou need to install the package withsetup.pyso the documentation is generated in the current directory.Alternative build systemsDocInit currently only parses Setuptoolssetup.cfgfiles. We plan to add support for other build systems as well, such asFlitandPoetry, which rely onpyproject.tomlfiles.