Update __init__.py

[buhtz]

Fix #567

Please check carefully if this is correct.

[codecov[bot]]

Codecov Report

Patch and project coverage have no change.

Comparison is base (da6d0d3) 92.47% compared to head (161b5a8) 92.47%.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #571   +/-   ##
=======================================
  Coverage   92.47%   92.47%           
=======================================
  Files          47       47           
  Lines        8170     8170           
  Branches     1948     1948           
=======================================
  Hits         7555     7555           
  Misses        358      358           
  Partials      257      257           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Do you have feedback about the report comment? Let us know in this issue.

[tristanlatr]

Hi @Codeberg-AsGithubAlternative-buhtz, the back tic quotation mark is used in restructuredtext to signify a reference.

Here we use epytext, so the format to make a inline code element is C{code}. So I’m afraid you got confused here and you changes will not render as you like.

Look:

[tristanlatr]

Hi @Codeberg-AsGithubAlternative-buhtz,

Do you want to follow up on this PR ?

[buhtz]

Hi @tristanlatr I didn't understood your first answer. I even don'T understand if there really is a problem or not. So I am out of here I would say.

I also have no way to test the doc output before creating a new or modifying this PR. I love pydoctor but I won't waste more time of my life setting up sphinx beside of it. So I don't see how to test how my modifications will look like in HTML output.

I assume also that I am confused about the original doc text.

Sorry for wasting your time with an ugly PR.

[tristanlatr]

Hi @Codeberg-AsGithubAlternative-buhtz,

Thanks for your kind words regarding pydoctor.

I believe there is a comprehension issue, indeed. This changes have nothing to do with sphinx, maybe you got confused because the pydoctor theme that looks like readthedocs?

Your proposal is to replace some ' caracters with `. I guess that the intention was to add some markup to signify that what's in the quotation marks is literal text. BUT the docstring markup used here is epytext not restructuredtext, so it's not the backtic quotation mark we should use here but the epytext markup: C{}.

Ho and by the way, you should not have to setup sphinx and everything if you install tox and simply run tox -e docs.

Tell me if things are more clear now,

[buhtz]

OK, we comin closer. I used tox to check the results. To speak in HTML/CSS: My goal was to make inline code like this

<tt class="rst-docutils literal">E{code}</tt>

And now after upgrading the docs I (assume) to better understand how escaping is done. In the previous version it wasn't clear (for me).

This is how my result (local) looks like now:

And just to make it more obvious I changed the background color:

[buhtz]

I think I got it now. This is totaly wrong what I have done because I mixed Escaping with Inline-Code.

I will rewrite it later. Not tonight. ;)

Sorry, but I have to say that this example-docu doesn't make sense. E.g. the "URL" section.

This code is only understandable when read as code. The inline markup construct U{text<url>} is used

But when it is rendered in HTML it doesn't make sense anymore. I will update that, too. The user need to understand and learn without reading the original source file init.py

[tristanlatr]

Thanks for your input, note that there is also this docs about epytext: http://epydoc.sourceforge.net/manual-epytext.html which are fully applicable to pydoctor except the part about « Indexed Terms ».

I agree that our demo packages should improved. And better explained that they contains example code as well as extra documentation regarding the docformat syntax.

[buhtz]

So no please take a look. Would be glad to merge this because I don't use epydoc style. ;)