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.

Sign up for GitHub

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

Jump to bottom

Documentation upgrade #157

Closed
Morwenn opened this issue Sep 26, 2019 · 3 comments
Closed

Documentation upgrade #157

Morwenn opened this issue Sep 26, 2019 · 3 comments
Labels
documentation tooling
Milestone
1.8.0

Comments

@Morwenn
Copy link
Owner

Morwenn commented Sep 26, 2019 •
edited

This is a meta-issue about solving issues specific to the documentation and ideas about improving the state of things. Here is an unstructured list of issues, ideas and solutions:

  • I am currently the only one able to edit the wiki and thus update the documentation.
  • I could put the documentation in the code but it wouldn't have the nice layout of the wiki.
  • I could probably put the documentation in the main repository and craft a Travis that would upload it to the wiki (since it's another Git repository) to have the cake and eat it too.
  • If such a synchronization works, I probably want to only update the documentation when changes are pushed to some specific branch: it could be develop, and then I would need to make sure to replace a dummy tag cpp-version-next when I produce a new release.
  • This would allow to write documentation along with the code commits and to have it versioned in a consistent way. It would also ensure that every major version (1.x, 2.x) has its own documentation but that we can remove things and still find the documentation for the previous version.
  • If I do make an automatic synchronization through Travis, then I can actually partially generate the version uploaded on the wiki, which might allow to use tools such as MarkdownSnippets.
  • The name of the directory for documentation files should follow the pitchfork project layout because it's as good a solution as any other.
  • Write documentation about updating the documentation.
@Morwenn
Copy link
Owner Author

Morwenn commented Oct 21, 2019

New idea: have the document only reflect the files in master, and deactivate all the automatic Conan uploads on that branch since I now use conan-center-index to maintain an out-of-source cpp-sort Conan recipe. That way I can fix the documentation directly on master and have a WIP documentation on develop.

Morwenn added a commit that referenced this issue Oct 26, 2019
@Morwenn
Remove Conan upload from .travis.yml (issue #157)
0d2f210 
[ci skip]
@Morwenn
Copy link
Owner Author

Morwenn commented Sep 23, 2020

This issue is actually a perfect opportunity to try the new GitHub actions. The integration should be smooth enough since Actions make it easy to interact with a generated token.

Morwenn added a commit that referenced this issue Sep 23, 2020
@Morwenn
Embed wiki sources in a 'docs' subdirectory (issue #157)
cb2abe0 
The new subdirectory allows contributers to propose pull requests to
complete or fix the documentation, and also allows to enforce the good
practice of modifying the documentation along the code, making it easier
to track the changes to revert in the documentation if needed.

The new subdirectory was named "docs" to follow the Pitchfork project
layout conventions (https://github.com/vector-of-bool/pitchfork).

[ci skip]
Morwenn added a commit that referenced this issue Sep 23, 2020
@Morwenn
Add GitHub action to update GitHub wiki (#157)
ba45c93 
Whenever a push to master is performed, the new action uploads the files from the /docs subdirectory to the project's GitHub wiki. This allows to keep the documentation sources in the main project, to version them easily, and to have backups of old versions of the documentation per branch.

[ci skip]
@Morwenn Morwenn added this to the 1.8.0 milestone Sep 23, 2020
@Morwenn
Copy link
Owner Author

Morwenn commented Sep 27, 2020

A bunch has been done so far:

  • The wiki sources have been moved to the main sources.
  • They are in a docs subdirectory, following the Pitchfork layout.
  • A GitHub Action synchronizes uploads the documentation sources to the wiki whenever documentation changes are pushed to master.
  • Modifications to the wiki are blocked for non-maintainers.

Having the documentation improves the state of things in a variety of ways:

  • Code, tests and documentation can be committed at the same time, increasing the coupling and making it easier to track or revert related changes.
  • It makes it easier for non-maintainers to contribute to the documentation.
  • It is now possible to have a specific version of the library with a matching documentation.
  • The day we switch to version 2.0.0, it will be possible to cleanup the documentation and having the doc for version 1.x and 2.x live side by side in different branches.
  • The documentation is now easily browsable for a given release or branch.

That's reasonably good for now. I'm closing this issue and moving the additional ideas from the original posts to a new issue.

@Morwenn Morwenn closed this as completed Sep 27, 2020
@Morwenn Morwenn mentioned this issue Sep 28, 2020
Open
Morwenn added a commit that referenced this issue Nov 9, 2020
@Morwenn
Update Changelog.md
f60a70c 
Add new C++20 category to describe the new support for std::identity,
std::ranges::less and std::ranges::greater.

Remove the section about how bitmap_allocator might be used and the text
about the relevance of the page across old versions. The embedding of
the documentation into the main repository made that text useless
(issue #157).

[ci skip]
@Morwenn Morwenn mentioned this issue Jan 10, 2022
Closed
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation tooling
Projects
None yet
Milestone
1.8.0
Development

No branches or pull requests
1 participant
@Morwenn