]> git.madduck.net Git - etc/vim.git/commit

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Refactor docs / Maintenance of docs (#1456)
authorRichard Si <63936253+ichard26@users.noreply.github.com>
Sun, 24 May 2020 16:37:46 +0000 (12:37 -0400)
committerGitHub <noreply@github.com>
Sun, 24 May 2020 16:37:46 +0000 (09:37 -0700)
commit7403d95862ae54c3504a8003666e1a0739067894
tree8783593f17616f4caed453e5a860bdf07e9f2d0b
parent0196437f8e062817d3277bb1484de3fbdcb3e19d
Refactor docs / Maintenance of docs (#1456)

* Split code style and components documentation

Splits 'the_black_code_style', 'pragmatism', 'blackd',and 'black_primer'
into their own files. The exception being 'the_black_code_style' and
'pragmatism'. They have been merged into one 'the_black_code_style_and_pragmatism'
file.

These changes are being made because the README is becoming very long. And
a README isn't great if it dissuades its reader because of its length.

* Update the doc generation logic and configuration

With the moving of several sections in the README and the renaming of a
few files, 'conf.py' needs to be able to support custom sections.

This commit introduces DocSection which can be used to specify custom
sections of documentation. The information stored in DocSection will be
used by the process_sections function to read, process, and write the section
to CURRENT_DIR.

A large change has been made to the how the docs are prepared to be built.
Instead of just generating the files needed by reading the README, this
has a full chain of operations so custom sections are supported. First,
it reads the README and spits out a list of DocSection objects representing
the sections to be generated by process_sections. This is done since most
of the docs still live in README. Then along with the defined custom_sections
, the process_sections will be begin to process the DocSection objects.
It reads the information it needs to generate the section. Then fetches
the section's contents, calls processors required by the section to process
the section's contents, and finally writes the section to CURRENT_DIR.

This large change is so processing of the documentation can be done just
for the versions hosted on ReadTheDocs.org. An example processor using this
feature is a 'replace_links' processor. It will replace documentation
links that point to the docs hosted on GitHub with links that point to the
version hosted on ReadTheDocs.org. (I won't be coding that ATM)

This also means that files will be overwritten or created once the docs
have been built. It is annoying, since you have to 'git reset --hard'
and 'git clean -f -d' after each build, but there's nothing better. The old
system had the same side effects, so yeah :(

* Update filenames and delete unnecessary files

Update the filenames since 'the_black_code_style' and 'pragmatism' were
merged and 'contributing' was deleted in favor of 'contributing_to_black'.

All symlinks were deleted since their home (_build/generated) is no longer
used.

* Fix broken links and a few redirections

* Merge master into refactor_docs (manually done)

* Add my and most of @hugovk suggestions

Co-Authored-By: Hugo van Kemenade <hugovk@users.noreply.github.com>
* Add logging and improve configurability

Just some cleaning up up of the DocSection dataclass and added logging
support so you know what's going on.

* Rename a section and please the grammar gods of Black

Thanks @hugovk for the suggestion!

* Fix Markdown comments

* Add myself as an author :P

Seems like the right time.

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
18 files changed:
README.md
docs/authors.md [deleted symlink]
docs/black_primer.md [new file with mode: 0644]
docs/blackd.md [changed from symlink to file mode: 0644]
docs/change_log.md [deleted symlink]
docs/conf.py
docs/contributing.md [deleted symlink]
docs/contributing_to_black.md [deleted symlink]
docs/editor_integration.md [changed from symlink to file mode: 0644]
docs/ignoring_unmodified_files.md [deleted symlink]
docs/index.rst
docs/installation_and_usage.md [deleted symlink]
docs/license.md [deleted symlink]
docs/pyproject_toml.md [deleted symlink]
docs/show_your_style.md [deleted symlink]
docs/testimonials.md [deleted symlink]
docs/the_black_code_style.md [changed from symlink to file mode: 0644]
docs/version_control_integration.md [deleted symlink]