Package: jaepeto
Automated DocumentationThis project is in a private beta.
for more information on using the tool,
to provide feedback,
or request access for a friend or colleague,
contact the beta runners.N.b.this project calls an AWS API
with snippets of code
in order to generate documentation.
No code is stored.
Only your API key and a hash of your project name,
for the purposes of identifying usage,
are logged.Get startedRequirementspython 3.8or greaterpip install jaepetoIn the base directory of your project, create a.jaepeto.iniconfig fileRunjaepeto-initin a terminal in your project's base directory to generate a template configJaepeto API keyConfig filepyproject.toml (preferred)Configurejaepetoin your pyproject.toml file
under a[tool.jaepeto]section.
It can have the following fieldsFieldPurposeRequiredDefaultnameProject nameY-descriptionShort description of the projectN"SHORT PROJECT DESCRIPTION"srcdirPath to source code directory from the project rootY-packageName of the project codebase as imported in files (if not using local imports)NsrcdirlocalFor development purposes only. Iftrue, uses local server for testingNfalsedocdirPath to the folder in which generated docs should be saved..is project rootY-docnameName of the document to be generated. ".md" file suffix will be added if not presentNtechnical_doc.mdNote: strings in toml files must be wrapped in quotes.E.g.:[tool.jaepeto]
name = "jaepeto"
srcdir = "jaepeto"
docdir = "docs/"
docname = "README.md".jaepeto.iniInstead of a pyproject.toml, you can use a.jaepeto.inifile..jaepeto.inican have the following fields:HeaderFieldPurposeRequiredDefaultprojectnameProject nameY-projectdescriptionShort description of the projectN"SHORT PROJECT DESCRIPTION"projectsrcdirPath to source code directory from the project rootY-projectpackageName of the project codebase as imported in files (if not using local imports)NsrcdirprojectlocalFor development purposes only. Iftrue, uses local server for testingNfalseprojectlanguageThe predominant codebase languageNpythondocsdocdirPath to the folder in which generated docs should be saved..is project rootY-An example.jaepeto.iniis:[project]
name = MyCoolProject
language = python
srcdir = src/cool
package = cool

[docs]
docdir = .API KeyTo get full functionality ofjaepeto,
a (free) API key is needed.
If you have been invited to join
the private beta,
your coordinator will provide
an API key for
and your team members
to use.
To setup your API key,
create a.envfile in your project root
and give it the following fields.JAEPETO_API_KEY = <YOUR-API-KEY>IMPORTANT: DO NOT ADD.envTO SOURCE CONTROL. YOUR API KEY MUST REMAIN PRIVATE.Whenjaepetoreads your config file,
it usespython-dotenvto read environment variables
from the.envfile.Generate documentationVia CLI:In a terminal/command prompt,
navigate to the root directory of your project
and runjaepeto.CommandPurposejeapetoGenerates/updates technical documentationjaepeto codeUpdates code snippets in technical documentationVSCode:There is a VSCode extension for this tool.
Search forjaepetoin the marketplace.
The extension comes with additional features
for streamlining your entire documentation generation process.ConceptsDoc commentsJaepeto adds markdown comments to technical documentation
to signal the start
and end
of different sections,
to help you curate automated technical documentation.
For example<!---Jaepeto-section-code: e22c5ecb-myproj/folder/file.py-20-25--->tells Jaepeto that the following bit of documentation
is a code snippet
and gives some information on when it was generated.
If that snippet of code is updated over time,
Jaepeto will automatically track that code
and update the snippet.Fixed document sectionsHave a bit of documentation
which isn't autogenerated by Jaepeto?
Wrap the section in comments:<!---Jaepeto-section-fixed: <position><number>-start--->
Bit of documentation to fix in place.
Maybe add your logo here,
or a markdown badge?
<!---Jaepeto-section-fixed: <position><number>-end--->Where<position>istopto fix the section to the top
of the document
andbottomto fix it to the bottom,
and<number>is the order within the fixed sections.
E.g.<!---Jaepeto-section-fixed: top1-start--->would fix some documentation to the very top
of the document.LicenseYou may download this package via pip
and use as intended,but you may not copy,
share
or edit the code.
This is signified by the lack of specific license in the code.Development - Get startedRequirementsDeveloped withpython 3.9pip install -r requirements.txtpip install -r requirements-dev.txtpip install -e .In.jaepeto.iniadd the following tags:[project]
...
local = true
...This will calllocalhostinstead of the hosted server.
In a separate terminal,
run the web app locally in order to connect.Style GuideUseblackto format codeOther thanblackniches, adhere to PEPUseisortto sort importsUse numpy-style docstringsUse type hints and verify withmypyTestingCIPurpose.github/workflows/test.ymlRun linting and unit tests. Executes on all pull request branchesTesting performed withpytest.
Runpytest tests/unitto run unit tests.
There are integration tests
which should be run with a local API app running.