Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: [docs] Github wiki
Guys, the docs are already viewable on GitHub (they have a parser for Textile) so there is no need to move them elsewhere.
What I really need done at this point is for the exported MediaWiki files to be cleaned and edited (apart from any tag docs, which I’ve nearly finished myself). That just means cloning the repo, edit the Textile files in your favourite text editor, then commit back to the repo.
Use relative URL links in the Textile docs and then you can hop between the doc pages like on any normal site, once they are in the repo.
Offline
Re: [docs] Github wiki
Aaaaaaaah. I’ve been to that Txp docs project page a handful of times and never noticed the “index” link in the ReadMe line before. This has been a source of confusion for me (Github is a little confusing to me, as you know), partly because I keep expecting to see the actual index where the ReadMe file is.
But now that I see what’s going on there, I’ll try this cloning, pulling, humping stuff.
Offline
Re: [docs] Github wiki
Brilliant, thanks Destry.
I have done an initial skim through the exported wiki files and taken out some of the crud. It needs to be collated properly though – I’m sure a fair few files still there are either redundant or in dire need of updating.
You might want to look at some of the tag docs that I have already formatted, just to see the initial text formatting. It’s based on the documentation patterns that were discussed a while back (i.e., sentence case on headings, h1 main headings, h2 subhead, h3 sub-subhead, etc.).
Some of the tags docs also have some Jekyll tags at the start of the file (example) – I’ll be adding those into all files in due course but don’t worry about them too much right now.
Any GitHub questions then let me know!
Offline
Re: [docs] Github wiki
Github questions aplenty.
So, I see this, and I see the “clone” button (yellow) that you say we should do (clone the docs):
This results in this view in my local Github client, which I have no idea how to use. (Those other items you see under “Github” and “Other” I have no idea how to use either and would like to delete):
You say I should use whatever text editor I want, but hell if I know how to do that in relation to my local Github client. So, a little tutorial at this point would be useful.
Also, if I go to a given doc page, like Index, there is an “Edit” button:
I’m guessing that easy approach is not acceptable?
Am I the only one that has trouble understanding Github? If so, then maybe I shouldn’t be touching docs and can stop bugging people about it.
Offline
Re: [docs] Github wiki
Hi Destry,
You have commit rights to the documentation repo (as your are part of the Textpattern Documentation Team which Stef set up a few days back). That means you can just clone the repo (instead of a fork) using the Mac GitHub.app as you have correctly started to. Choose a place on your local hard disk to store it.
Then – ignore the GitHub.app for a minute – find the repo you have just saved on your computer. Within that repo you’ll find the Textile files. Edit any of those in a text editor or IDE. Once you save those changes , switch back to the GitHub.app and under the ‘changes’ tab for that repo you’ll see the amends you have made.
Make sure the files you want to commit are ticked, then give the changes a brief summary description and press the ‘Commit to’ button below it. That effectively takes a snapshot of those changes in your local version control. You can repeat the above again to make a few commits, or continue to sync the local snapshots back to the repo on GitHub itself (i.e., the non-local version of the repo) using the sync button in the top-right of the GitHub.app window.
It’s wise to sync the local clone and GitHub repo quite often as any changes other people make will then be pulled down to your local clone.
—
The other way you pointed out, editing directly on GitHub, is equally as viable and quicker for sure, if you are happy to edit within a browser window. I sometimes to that for really quick edits.
Even then, remember to sync those changes back to your local clone at some point.
—
You can certainly delete the other local clones you have, that doesn’t delete the original repo at GitHub, just your local clones of them. Even when you remove in GitHub.app the local clone is still on your hard disk until you actually bin it.
Offline
Re: [docs] Github wiki
Thanks for the Github tutorial – useful for me too ;-)
Offline
Re: [docs] Github wiki
Thanks Phil, that helped a lot.
Offline
Re: [docs] Github wiki
What does it mean if I can “clone” a repo or github wiki, make changes locally, use the local Github client to commit those changes, and I get this error?
AUTHENTICATION FAILED
You may not have permission to access {resource}. Check Preferences to make sure you’re still logged in.
I would have thought being able to clone the repo/wiki meant I had access.
Offline
Re: [docs] Github wiki
Destry wrote #293695:
What does it mean if I can “clone” a repo or github wiki, make changes locally, use the local Github client to commit those changes, and I get this error?
[…]
I would have thought being able to clone the repo/wiki meant I had access.
Fork first. Make changes to your fork locally, commit changes to your fork, and when you’re happy with your fork, raise a pull request to have the original repo/wiki pull your changes in.
Edit: oh, my bad – if you’re doing it directly then this is all irrelevant. Missed that part. Sorry.
Last edited by gaekwad (2015-07-26 12:39:30)
Offline
Re: [docs] Github wiki
I also had problems pushing data back to my repo on Github – I futzed for 2 hours yesterday until I managed to get it to work https://help.github.com/articles/generating-ssh-keys/
Offline
Re: [docs] Github wiki
Just as an update, there is the beginnings of a new documentation site coming together. Bear in mind this is a proof of concept – no layouts or final styling has been done yet…
Jekyll is quarter built so far.
Note the domain name. This won’t be housed on .net or .com due to lack of ownership of those domains by Textpattern.
Offline
Re: [docs] Github wiki
philwareham wrote #293899:
Suggestion…
Since we’re editing in Github and porting to Jekyll, we need a process so it’s not confusing editing efforts, nor visitors to the new Jekyll site (now that you’ve made the link public). So, how about this:
We can leave the main index at Jekyll, as you have it, but remove all links there for any doc pages that are not actually ready or ported there yet. (E.g., files with .textile extension are auto-downloaded if their links are clicked, so that’s not good.) Then we add links only when the editing for that page is primarily done and configured for Jekyll’s happiness.
Page editor notifies you (the porter) when a given page is ready for transfer, perhaps using an Issue ticket, which indicates the file in question.
Then you port the page into the Jekyll file tree exactly as it’s positioned in the Github version and link up any page on the index that it might concern. (All other pages below index should just work.)
Something like that?
Offline
Re: [docs] Github wiki
The GitHub files and Jekyll files are one and the same. All that needs to be done is to add the Jekyll frontmatter code at the top of each Textile file and it instantly becomes part of the Jekyll site. Plus remove affixes from hyperlinks within docs.
Offline
Re: [docs] Github wiki
Ah.. Okay. Magic.
Offline