Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove indentation causing RST errors #1495

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

melissamahoney-mongodb
Copy link

@melissamahoney-mongodb melissamahoney-mongodb commented Sep 23, 2021

We generate our docs in RST from Cobra. I removed the indentations causing an error in the generated RST. This also makes the long descriptions consistent with the other completion commands.

@CLAassistant
Copy link

CLAassistant commented Sep 23, 2021

CLA assistant check
All committers have signed the CLA.

@@ -616,9 +616,9 @@ $ source <(%[1]s completion bash)

To load completions for every new session, execute once:
Linux:
$ %[1]s completion bash > /etc/bash_completion.d/%[1]s
$ %[1]s completion bash > /etc/bash_completion.d/%[1]s
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe keep the indentation and add .. code:: sh before? See https://docutils.sourceforge.io/docs/ref/rst/directives.html#code

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would this be interpreted correctly for the help message @umarcor ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be honest, I am genuinely confused. To my understanding, the help message is printed to screen/terminal, so unrelated to RST. My previous reply was considering that line 619 is going to end being part of a restructuredtext file. However, I now see why you are asking, since this is indeed the "Long" field of a command. Is the same text source used for both printing the help in screen and for generating the rst docs?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's definitely used for the help message and I'm learning with this PR that it is also used for RST. So the original idea of removing the indentation is probably the best way forward. What do you think?

Copy link
Contributor

@umarcor umarcor Sep 25, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is technically not correct to remove the indentation, because the resulting RST is not semantically valid. However, given the constraints, I believe it's fair enough. It allows removing the error found by @melissamahoney-mongodb and we don't need to learn the details of doc generation right now. I'll mark this dialogue as resolved, and we'll deal with docgen some other day 😉.

EDIT

It seems I cannot mark it as resolved myself. @melissamahoney-mongodb, do you mind marking, please?

umarcor pushed a commit to umarcor/cobra that referenced this pull request Nov 5, 2021
umarcor pushed a commit to umarcor/cobra that referenced this pull request Nov 15, 2021
umarcor pushed a commit to umarcor/cobra that referenced this pull request Nov 16, 2021
@github-actions
Copy link

This PR is being marked as stale due to a long period of inactivity

@marckhouzam
Copy link
Collaborator

I think this PR is giving problems:

  1. it removes indentation while fix: improve completions help formatting #1444 adds indentation. When both are joined in 🍁 Fall 2021 - release candidate #1525 we are not consistent with the indentation between completion bash -h and the other shells (e.g., completion zsh -h)
  2. the indentation allows nice code-block formatting in markdown, so I feel it is better to have it than not

@melissamahoney-mongodb can you specify how you get an error when generating RST doc? I haven't been able to reproduce it.

@umarcor what do you think? I personally would pull this out of the release candidate until we can clarify the situation.

@umarcor
Copy link
Contributor

umarcor commented Nov 25, 2021

@marckhouzam I removed this from #1496 and I pulled it out of #1525.

It seems that supporting multiple output formats might require explicitly handling multiple text sources...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants