Our style guide and flake8 require that lines in our Python code do not exceed 80 characters. Some docstrings do not follow this convention and should be reformatted to follow it when possible.
You can find a list of such strings with this command: grep '""" *# noqa' ../*/swh -r.
The following packages have offending lines. I will fix the lines wherever possible.
I have checked autopep8 and black, none of these claim to reformat long doc strings properly. This may require custom scripting or editing it by hand. However autopep8 did suggest some other changes when I tried it out. Is there a reason a linter is used instead of a formatter?
This should probably be reformatted manually, because our docstrings use special formats (used by sphinx and sphinxcontrib-httpdomain when building the documentation), which these tools are not aware of and may break.
Though I admit I'm not familiar with any reformatting tool, so it's possible they support it.
"""Django view that produces an HTML display of a content identified
by its hash value.
The url that points to it is :http:get:`/browse/content/[(algo_hash):](hash)/`
Many docstrings are of this type, where the 80 character mark is here ^.
""" # noqa"""Django view that produces an HTML display of a content identified
by its hash value.
The url that points to it is
:http:get:`/browse/content/[(algo_hash):](hash)/`
""" # noqaThis is one possible solution but it reduces readability, I will avoid making changes in such cases.
what is the expected formatting for snippets like these
the 80 character mark is -----------------------------------------------------------------|
@browse_route(r'origin/(?P<origin_type>[a-z]+)/url/(?P<origin_url>.+)/visit/(?P<timestamp>.+)/directory/', # noqa
r'origin/(?P<origin_type>[a-z]+)/url/(?P<origin_url>.+)/visit/(?P<timestamp>.+)/directory/(?P<path>.+)/', # noqa
r'origin/(?P<origin_type>[a-z]+)/url/(?P<origin_url>.+)/directory/', # noqa
r'origin/(?P<origin_type>[a-z]+)/url/(?P<origin_url>.+)/directory/(?P<path>.+)/', # noqa
r'origin/(?P<origin_url>.+)/visit/(?P<timestamp>.+)/directory/', # noqa
r'origin/(?P<origin_url>.+)/visit/(?P<timestamp>.+)/directory/(?P<path>.+)/', # noqa
r'origin/(?P<origin_url>.+)/directory/', # noqa
r'origin/(?P<origin_url>.+)/directory/(?P<path>.+)/', # noqa
view_name='browse-origin-directory')
def origin_directory_browse(request, origin_url, origin_type=None,
timestamp=None, path=None):
"""Django view for browsing the content of a directory associated
to an origin for a given visit.
The url scheme that points to it is the following:
* :http:get:`/browse/origin/[(origin_type)/url/](origin_url)/directory/[(path)/]`
* :http:get:`/browse/origin/[(origin_type)/url/](origin_url)/visit/(timestamp)/directory/[(path)/]`
""" # noqa
return browse_snapshot_directory(
request, origin_type=origin_type, origin_url=origin_url,
timestamp=timestamp, path=path)From my point of view, it is not a big deal if some docstrings and url declarations exceed the 80 columns limit.
I originally did that in order to have each url on a single line for better readability.
Nervertheless, those kind of formatting could be used to avoid some # noqa use:
the 80 character mark is -----------------------------------------------------------------|
@browse_route(r('origin/(?P<origin_type>[a-z]+)/url/(?P<origin_url>.+)'
'/visit/(?P<timestamp>.+)/directory/'),Nevertheless, the :http:get: lines must not be changed as this will break the generated Sphinx documentation.
I followed swh-docker-dev documentation to host the setup locally. But it only hosts the web portal, I couldn't access locally hosted documentation. How can I see the effect my changes are making?
I followed swh-docker-dev documentation to host the setup locally. But it only hosts the web portal, I couldn't access locally hosted documentation. How can I see the effect my changes are making?
As far as i know, we do not use the docker-environment for the documentation.
The documentation changes can be seen through the swh-docs repository.
Please, have a look in that repository's readme (it orchestrates the documentation generation through a Makefile and i believe all is explained there).
You can then check the generated files through your own browser.
Cheers,