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

fix #467, "docstring oddities #662

Merged
merged 4 commits into from
Oct 28, 2020
Merged

fix #467, "docstring oddities #662

merged 4 commits into from
Oct 28, 2020

Conversation

rfourquet
Copy link
Contributor

@rfourquet rfourquet commented Oct 24, 2020

Thee commits (which make it easier to review, so github highlights the parts which changed)

  1. align signature to 4 spaces (just one signature, the rest was fixed in a previous PR)
  2. add a line between the signature and the description
  3. remove > characters at the beginning of lines in docstrings.

I used Perl commands (included in the commit messages), so this limit the chance for human errors, but I'm not expert in regexes either... I also reviewed "manually", and this seems to have done what was expected.

Perl command:
perl -i -p -e 'BEGIN{undef $/;}  s/"""\n   (\S)/"""\n    \1/smg' $(find -name \*\.jl)
Perl command:
perl -i -p -e 'BEGIN{undef $/;}  s/"""\n    (\S.*)\n>/"""\n    \1\n\n>/g' $(find -name \*\.jl)
Perl commands:
perl -i -p -e 's/^> (.+)/\1/g' $(find -name \*\.jl)
perl -i -p -e 's/^>$//g' $(find -name \*\.jl)
@rfourquet rfourquet added the doc This change adds or pertains to documentation label Oct 24, 2020
@wbhart
Copy link
Contributor

wbhart commented Oct 26, 2020

Looks like this causes the docs to stop building. See the documentation test on travis.

@fieker
Copy link
Contributor

fieker commented Oct 27, 2020 via email

@rfourquet
Copy link
Contributor Author

Not helpful, but looks like an error in documenter

Yes... I force-pushed on another PR to check if the build still passes there.

@rfourquet
Copy link
Contributor Author

A painfully boring bisection allowed to find the problem, a $\times $ in a docstring, documenter is not happy to have a space before the closing $. I'm not sure whether this is a bug in Documenter.jl (maybe it's documented?), but surely documenter could make it easier to find the problem (or did I miss an easier way to find it?)

@thofma
Copy link
Member

thofma commented Oct 27, 2020

The julia markdown parser is very brittle when it comes to $. There are is at least one open issue at the julia repository, not sure if it is related.

@rfourquet rfourquet merged commit f3962fb into master Oct 28, 2020
@rfourquet rfourquet deleted the rf/docstring-format branch October 28, 2020 09:12
@rfourquet
Copy link
Contributor Author

There is also this issue: JuliaDocs/Documenter.jl#1020

@rfourquet rfourquet changed the title fix #467, "docstring odditites fix #467, "docstring oddities Nov 2, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc This change adds or pertains to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants