Open ruebot opened 8 years ago
can we use git tags to version docs in master? then in master have a directory for each release
@kimpham54 maybe. But, the repo includes all of the 7.x tags as well, and we don't have any tags for 7.x-2.x. The @Islandora-CLAW/committers will need to determine if we should "release"/tag any of that work, of if we just move on from it and abandon it. We'll probably what to draft a policy for how we handle documentation moving forward. If that is something you want to work on, and @dannylamb is cool with that, I think that would be a good start. All that said, the August sprint is probably going to be hyper-concentrated on the MVP.
OK, I can take this on this sprint but plenty of work to do still with #281 so happy to wait as well
@ruebot at least tag it. we're not just going to nuke it.
@kimpham54 handling documentation per version is a very valuable goal and could be done independent of mvp design. i'll put an item on the agenda for the claw call if you have any ideas you want to share, or if you want to talk strategy with anyone.
@dannylamb might as well add an agenda items about what we're going to tag then, because we'll definitely need to talk that out.
@ruebot done
Another option to consider: http://couscous.io/
@kimpham54 we're already setup for that with MkDocs; http://islandora-claw.github.io/CLAW/ is ghpages.
I looked into the possibility of viewing deployed tagged versions of documentation by tagging master in gh-pages. This doesn't seem possible from what I can tell. As an alternative proposal to view previous versions, we can create a new directory to organize the documentation for each new release:
7.x-2.2 (current) accessed at http://islandora-claw.github.io/CLAW/7.x-2.2/ --| What is Islandora? accessed at http://islandora-claw.github.io/CLAW/7.x-2.2/about --| What's new? --| Contributing --| Chullo --| Alpaca --| etc. 7.x-2.1 accessed at http://islandora-claw.github.io/CLAW/7.x-2.1/ --| What is Islandora? accessed at http://islandora-claw.github.io/CLAW/7.x-2.1/about --| What's new? --| Contributing --| Chullo --| Alpaca --| etc. 7.x-2.0 accessed at http://islandora-claw.github.io/CLAW/7.x-2.0/ --| What is Islandora? accessed at http://islandora-claw.github.io/CLAW/7.x-2.0/about --| What's new? --| Contributing --| Chullo --| Alpaca --| etc.
Tagging can still be useful if a tag is created for a release, it can trigger a webhook to deploy the new version of the docs to gh-pages. You can also use webhooks to deploy docs on a regular basis between releases.
Webhooks can also easily let others contribute to the documentation - once a doc contributor proposes a file change via pull request which once this is approved it can be deployed to gh-pages.
Proposed Workflow:
@dannylamb if you have any comments or suggestions, i'd be happy to look into other options for this sprint
Would it be helpful if we set up a test repository, and actually try some of these options out? Like with a fake release?
sure, I could work on that
I created a copy of the islandora docs in my own repo, https://kimpham54.github.io/CLAW/. I think I understand the crux of the workflow now.
I see now that one of the issues is that the docs have symlinks to READMEs in other repositories, so to version those docs could be a pain. Is it an option to have all of the docs just in the CLAW repo, without symlinks? Then the problem becomes how to keep each component's README in sync with the READMEs in CLAW/docs.
If someone's available tomorrow I'd like to understand how the docs are being deployed to gh-pages right now, because I'm not sure the way I'm doing it is the way that that the docs are actually being updated.
@kimpham54
I'd like to understand how the docs are being deployed to gh-pages right now
https://github.com/Islandora-CLAW/CLAW/blob/master/docs/technical-documentation/docs-build.md
@ruebot thanks nick. just a couple of questions:
@kimpham54
git submodule update --init --recursive
?.gitignore
isn't in the gh-pages branch: https://github.com/Islandora-CLAW/CLAW/tree/gh-pages@ruebot
going to look into this more tomorrow, thanks
A first kick at the can: https://kimpham54.github.io/CLAW/
This is how the docs are structured: https://github.com/kimpham54/CLAW/tree/master/docs (symlinks aren't fixed in 8x12-currentRelease, I couldn't figure out how to do it yet and so the docs didn't all build)
I think symbolic links should be removed, and instead use webhooks (? if possible) to mirror the READMEs in each submodule repository to the READMEs in CLAW/docs/[submodule]/README.md. That way all documentation can live in one place, which will be simpler for contributors should they wish to add additional .md files. They would add it to docs/[submodule] instead of the submodule repo itself. You wouldn't have to keep making symlink docs in CLAW/docs. Submodules would only have READMEs that stay in sync with the READMEs in docs/.
Then, for every release:
Notes:
Any comments or other suggestions on what I should look into next are welcome
Looking at the navigation here, I find it very confusing.
mkdocs didn't like naming of the directories 8.x-1.0/ 8.x-1.1/ it collapsed those top level folders. had to change it to 8x10/ 8x11/
This would have to follow semantic versioning, given the Versioning Policy
...what if we took a step back, and looked at this is a different way. Is there anything that says that we have to have a full set of documentation for every version? Would it be too naive to say that we just have documentation, and if we have any version specific documentation, we wrap it in version headers or warnings. Then, go through a deprecation cycle, just like we would with code?
if you want documentation by release, we could probably use custom css to override the way that the links are being displayed in navigation. we could collapse the subheadings and links.
the solution is a little complex, so maybe it's not the best approach to managing documentation if having full documentation for every release is not required. i guess it depends on how people intend to use the documentation.
instead, you could have release notes highlighting what changes have been made, what documentation has been changed and deprecating
Hmm... I think we need to work on the sidebar for sure. Best to collapse entirely the non-selected version.
Also, when I choose the Home link under a release it only seems to highlight part of that section. It doesn't include the sub-repos.
Lastly, we might need to re-write links so the Alpaca link under 8x-11/Home points to the 8x-11/Alpaca/README.md, currently it points to github.com (which is the current version).
Have you considered Read the Docs? It seems like it can do what you want. http://docs.readthedocs.io/en/latest/versions.html
Example from Omeka: http://omeka.readthedocs.io/
@rdeanlib I'll take a look at this - thanks!
Demo of CLAW documentation by tag using readthedocs: http://islandora-claw-kimpham54.readthedocs.io/en/latest/ (you can switch to different versions of the docs by clicking on "Read the docs" link at the bottom left hand corner.
For now it seems like readthedocs isn't pulling in the READMEs from the submodules like mkdocs alone: https://kimpham54.github.io/CLAW/ - this might not be an issue if you want all your docs to reside in one repository.
Link to the readthedocs project: https://readthedocs.org/projects/islandora-claw-kimpham54/
Does this seem like a better approach? Again comments and suggestions are welcome
other issues i've noticed:
sphinx seems to be better supported with readthedocs than mkdocs, so that might be worth testing?
So I've been playing around with some of the different options again, and would like to see if any of these options stand out for anyone in particular to pursue. I've included some of my thoughts on each platform below.
readthedocs: restructuredtext (sphinx)
readthedocs: mkdocs
mkdocs standalone
FEATURE REVIEW
easily view and edit different versions for release documentation mkdocs - no, unless you do so from github sphinx (readthedocs) - yes mkdocs (readthedocs) - yes
easily edit and clear path to do so from html page to github repository mkdocs - yes sphinx (readthedocs) - somewhat mkdocs (readthedocs) - no
notes:
flexible enough to support docs all in one place or docs embedded with code in separate repos mkdocs - yes sphinx (readthedocs) - yes mkdocs (readthedocs) - yes, but needs to be tested
notes:
also is there any interest using confluence again?
:-1: Confluence
Awesome job @kimpham54, regarding the question of "easily edit and clear path..." you said "somewhat" for sphinx. Could you elaborate a little?
@whikloj I certainly can. Sphinx's use of reStructuredText at first glance has similar, easy-to-read syntax as markdown, but if we want it to be it can become a lot more complex using semantic markup (http://www.sphinx-doc.org/en/stable/markup/index.html) that isn't supported in Github. To get started with Sphinx, there are also a lot of additional built-in modules and configuration setup pages. It doesn't mean we have to use the complex syntax but it's there as a possibility and if someone decides to use it, it may be harder to maintain or convince other contributors to follow those conventions. It's also worth noting that when I did a quick search for package support in sublimetext, atom, and repos in github for markdown vs restructuredtext it also seems like markdown as a general format is more widely used.
I was reviewing this ticket and wanted to provide an update on versioning with github pages. @ruebot referenced this ticket https://github.com/mkdocs/mkdocs/issues/193 earlier in the conversation, which is not yet resolved. The versioning feature based on github tags works with readthedocs, however readthedocs only supports sphinx and its own flavour of mkdocs (not compatible with newer versions of mkdocs nor with the material theme that we are currently using).
I'm not sure how to move this ticket forward, other than to suggest that if we have those processes in place (such as coordinating tags across repositories for releases) that would be a step in the right direction. Does anyone have experience with automating this via github webhooks or something similar?
Might be a good topic of discussion for the documentation team at the hackfest here in a couple weeks. @manez, that sound ok?
@ruebot we can always suggest it for a topic 👍
I have seen the light, use single page README.adoc: http://www.cirosantilli.com/markdown-style-guide/#use-asciidoc
I faced same challenge and solved it using GitHub actions. Details is described in this stackoverflow answer.
Apparantly the material theme we're using has this as a paid feature: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#versioning
We are now subscribing to the paid features, but have not implemented this one.
@eldonquijote tested MkDocs Material versioning with mike and found it to work. Requires changing the Travis configuration to invoke mike instead of mkdocs.
Currently, the way we use MkDocs and ghpages, we don't have a way to version documentation. As we are moving away from the 7.x-2.x branch, I would like to see that documentation still exist, but, at the same time, we need documentation for the master branch.
Let's use this issue for strategizing a way accomplish this.
One option to kick off the discussion would be to just move the 7.x-2.x documentation over to the master branch in a directory, and map it out from there.