Python Sphinx documentation generation using google style guide
.everyoneloves__top-leaderboard:empty,.everyoneloves__mid-leaderboard:empty,.everyoneloves__bot-mid-leaderboard:empty{ height:90px;width:728px;box-sizing:border-box;
}
I am fairly new to Python and therefore used the style guides of google (https://github.com/google/styleguide/blob/gh-pages/pyguide.md) to get a nice and clean looking code.
Now I came across the problem, that I want to have a documentation created out of these comments for methods and modules and found out apparently Sphinx is the tool to use for it.
Furthermore I found out, that following extension for Sphinx could be used to generate the documentation out of it, using the Google Python style guide:
https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
However I am failing with two points:
- How do I have to include this extension to work properly?
- How do I have to call Sphinx in order to have a complete documentation of my methods and modules?
- (optional) Is there a way to integrate it into PyCharm (professional)?
Following you can find one of my methods (only the comments), which I am trying to generate a documentation for:
def _get_lifecycle_environments(self: object) -> dict:
"""Gets all lifecycle environments
Gets all lifecycle environment from the Satellite server
Args:
Returns:
dict: The name and IDs of all lifecycle environments of the Satellite server. If there are no lifecycle
environments an empty dictionary is returned.
Example of a dict with lifecycle environments and their IDs:
{
'Library': 1,
'lce-default-dev': 2,
'lce-default-prod': 3,
'lce-default-test': 4
}
Raises:
RuntimeError: If the API call fails for some reason
KeyError: If the expected key 'results' is not in the result
KeyError: If the expected key 'name' is not in the result of a lifecycle environment or is None
TypeError: If the expected key 'name' is not a string
KeyError: If the expected key 'id' is not in the result of a lifecycle environment or is None
TypeError: If the expected key 'id' is not a integer
"""
python-3.x python-sphinx documentation-generation
edited Nov 24 '18 at 17:15
mzjn
32.6k670160
asked Nov 24 '18 at 16:39
SteffenSteffen
1
add a comment |
I am fairly new to Python and therefore used the style guides of google (https://github.com/google/styleguide/blob/gh-pages/pyguide.md) to get a nice and clean looking code.
Now I came across the problem, that I want to have a documentation created out of these comments for methods and modules and found out apparently Sphinx is the tool to use for it.
Furthermore I found out, that following extension for Sphinx could be used to generate the documentation out of it, using the Google Python style guide:
https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
However I am failing with two points:
- How do I have to include this extension to work properly?
- How do I have to call Sphinx in order to have a complete documentation of my methods and modules?
- (optional) Is there a way to integrate it into PyCharm (professional)?
Following you can find one of my methods (only the comments), which I am trying to generate a documentation for:
def _get_lifecycle_environments(self: object) -> dict:
"""Gets all lifecycle environments
Gets all lifecycle environment from the Satellite server
Args:
Returns:
dict: The name and IDs of all lifecycle environments of the Satellite server. If there are no lifecycle
environments an empty dictionary is returned.
Example of a dict with lifecycle environments and their IDs:
{
'Library': 1,
'lce-default-dev': 2,
'lce-default-prod': 3,
'lce-default-test': 4
}
Raises:
RuntimeError: If the API call fails for some reason
KeyError: If the expected key 'results' is not in the result
KeyError: If the expected key 'name' is not in the result of a lifecycle environment or is None
TypeError: If the expected key 'name' is not a string
KeyError: If the expected key 'id' is not in the result of a lifecycle environment or is None
TypeError: If the expected key 'id' is not a integer
"""
python-3.x python-sphinx documentation-generation
edited Nov 24 '18 at 17:15
mzjn
32.6k670160
asked Nov 24 '18 at 16:39
SteffenSteffen
1
You will need to read aboutautosummaryandautodoc. The former generates stub .rst files with directives that will consume your docstrings, then autodoc will output your docstrings from the stub files.
– Steve Piercy
Nov 24 '18 at 19:04
add a comment |
I am fairly new to Python and therefore used the style guides of google (https://github.com/google/styleguide/blob/gh-pages/pyguide.md) to get a nice and clean looking code.
Now I came across the problem, that I want to have a documentation created out of these comments for methods and modules and found out apparently Sphinx is the tool to use for it.
Furthermore I found out, that following extension for Sphinx could be used to generate the documentation out of it, using the Google Python style guide:
https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
However I am failing with two points:
- How do I have to include this extension to work properly?
- How do I have to call Sphinx in order to have a complete documentation of my methods and modules?
- (optional) Is there a way to integrate it into PyCharm (professional)?
Following you can find one of my methods (only the comments), which I am trying to generate a documentation for:
def _get_lifecycle_environments(self: object) -> dict:
"""Gets all lifecycle environments
Gets all lifecycle environment from the Satellite server
Args:
Returns:
dict: The name and IDs of all lifecycle environments of the Satellite server. If there are no lifecycle
environments an empty dictionary is returned.
Example of a dict with lifecycle environments and their IDs:
{
'Library': 1,
'lce-default-dev': 2,
'lce-default-prod': 3,
'lce-default-test': 4
}
Raises:
RuntimeError: If the API call fails for some reason
KeyError: If the expected key 'results' is not in the result
KeyError: If the expected key 'name' is not in the result of a lifecycle environment or is None
TypeError: If the expected key 'name' is not a string
KeyError: If the expected key 'id' is not in the result of a lifecycle environment or is None
TypeError: If the expected key 'id' is not a integer
"""
python-3.x python-sphinx documentation-generation
edited Nov 24 '18 at 17:15
mzjn
32.6k670160
asked Nov 24 '18 at 16:39
SteffenSteffen
1
I am fairly new to Python and therefore used the style guides of google (https://github.com/google/styleguide/blob/gh-pages/pyguide.md) to get a nice and clean looking code.
Now I came across the problem, that I want to have a documentation created out of these comments for methods and modules and found out apparently Sphinx is the tool to use for it.
Furthermore I found out, that following extension for Sphinx could be used to generate the documentation out of it, using the Google Python style guide:
https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
However I am failing with two points:
- How do I have to include this extension to work properly?
- How do I have to call Sphinx in order to have a complete documentation of my methods and modules?
- (optional) Is there a way to integrate it into PyCharm (professional)?
Following you can find one of my methods (only the comments), which I am trying to generate a documentation for:
def _get_lifecycle_environments(self: object) -> dict:
"""Gets all lifecycle environments
Gets all lifecycle environment from the Satellite server
Args:
Returns:
dict: The name and IDs of all lifecycle environments of the Satellite server. If there are no lifecycle
environments an empty dictionary is returned.
Example of a dict with lifecycle environments and their IDs:
{
'Library': 1,
'lce-default-dev': 2,
'lce-default-prod': 3,
'lce-default-test': 4
}
Raises:
RuntimeError: If the API call fails for some reason
KeyError: If the expected key 'results' is not in the result
KeyError: If the expected key 'name' is not in the result of a lifecycle environment or is None
TypeError: If the expected key 'name' is not a string
KeyError: If the expected key 'id' is not in the result of a lifecycle environment or is None
TypeError: If the expected key 'id' is not a integer
"""
python-3.x python-sphinx documentation-generation
python-3.x python-sphinx documentation-generation
edited Nov 24 '18 at 17:15
mzjn
32.6k670160
asked Nov 24 '18 at 16:39
SteffenSteffen
1
edited Nov 24 '18 at 17:15
mzjn
32.6k670160
asked Nov 24 '18 at 16:39
SteffenSteffen
1
edited Nov 24 '18 at 17:15
mzjn
32.6k670160
edited Nov 24 '18 at 17:15
mzjn
32.6k670160
edited Nov 24 '18 at 17:15
mzjn
32.6k670160
32.6k670160
asked Nov 24 '18 at 16:39
SteffenSteffen
1
asked Nov 24 '18 at 16:39
SteffenSteffen
1
asked Nov 24 '18 at 16:39
SteffenSteffen
1
1
You will need to read aboutautosummaryandautodoc. The former generates stub .rst files with directives that will consume your docstrings, then autodoc will output your docstrings from the stub files.
– Steve Piercy
Nov 24 '18 at 19:04
add a comment |
You will need to read aboutautosummaryandautodoc. The former generates stub .rst files with directives that will consume your docstrings, then autodoc will output your docstrings from the stub files.
– Steve Piercy
Nov 24 '18 at 19:04
You will need to read about
autosummary and autodoc. The former generates stub .rst files with directives that will consume your docstrings, then autodoc will output your docstrings from the stub files.– Steve Piercy
Nov 24 '18 at 19:04
You will need to read about
autosummary and autodoc. The former generates stub .rst files with directives that will consume your docstrings, then autodoc will output your docstrings from the stub files.– Steve Piercy
Nov 24 '18 at 19:04
add a comment |
0
active
oldest
votes
Your Answer
StackExchange.ifUsing("editor", function () {
StackExchange.using("externalEditor", function () {
StackExchange.using("snippets", function () {
StackExchange.snippets.init();
});
});
}, "code-snippets");
StackExchange.ready(function() {
var channelOptions = {
tags: "".split(" "),
id: "1"
};
initTagRenderer("".split(" "), "".split(" "), channelOptions);
StackExchange.using("externalEditor", function() {
// Have to fire editor after snippets, if snippets enabled
if (StackExchange.settings.snippets.snippetsEnabled) {
StackExchange.using("snippets", function() {
createEditor();
});
}
else {
createEditor();
}
});
function createEditor() {
StackExchange.prepareEditor({
heartbeatType: 'answer',
autoActivateHeartbeat: false,
convertImagesToLinks: true,
noModals: true,
showLowRepImageUploadWarning: true,
reputationToPostImages: 10,
bindNavPrevention: true,
postfix: "",
imageUploader: {
brandingHtml: "Powered by u003ca class="icon-imgur-white" href="https://imgur.com/"u003eu003c/au003e",
contentPolicyHtml: "User contributions licensed under u003ca href="https://creativecommons.org/licenses/by-sa/3.0/"u003ecc by-sa 3.0 with attribution requiredu003c/au003e u003ca href="https://stackoverflow.com/legal/content-policy"u003e(content policy)u003c/au003e",
allowUrls: true
},
onDemand: true,
discardSelector: ".discard-answer"
,immediatelyShowMarkdownHelp:true
});
}
});
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f53460233%2fpython-sphinx-documentation-generation-using-google-style-guide%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
0
active
oldest
votes
0
active
oldest
votes
active
oldest
votes
active
oldest
votes
Thanks for contributing an answer to Stack Overflow!
- Please be sure to answer the question. Provide details and share your research!
But avoid …
- Asking for help, clarification, or responding to other answers.
- Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f53460233%2fpython-sphinx-documentation-generation-using-google-style-guide%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
You will need to read about
autosummaryandautodoc. The former generates stub .rst files with directives that will consume your docstrings, then autodoc will output your docstrings from the stub files.– Steve Piercy
Nov 24 '18 at 19:04