Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
I am posting this question despite it possibly being off-topic, since I can't find a better place to ask:
I am publishing a scientific paper and use some analysis code which I want to be publicly available. I wrote a general purpose analysis library (Matlab) and put it onto github. Then there is a little script that uses that library for the specific purpose of this very paper. What is the best way to publish that script?
I see the following options where to publish this script:
publish into a new repository with only one file which is referenced in the paper (isn't that an overkill?)
append analysis script as supplementary information to the paper (not very accessible and usable for other people)
add to the same repository as the library (does not make sense since the library is general purpose while the script is for a single specific purpose)
Happy about any feedback, re-directions or discussions.
I don't know if the best method, but here's what I did with one of my own Matlab libraries, SHCTools, to make it publicly available for a journal article:
Created new branch of the repository (as opposed to an entirely new repository). This way the two are co-located, but the paper-specific branch can remain stable allowing readers to replicate results even after the main repository changes significantly.
Added a notice to the main branch's README.md file linking to the new stable branch.
Added a folder to the new stable branch containing M-files that re-create the figures in may paper (you could do the same with examples).
Adding a script as a supplemental resource (perhaps inside an examples or contrib directory) would seem like an acceptable and reasonably standard arrangement.
For a free-standing script, perhaps consider publishing it as a gist; this is a secondary service of Github for simple standalone snippets.
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 6 years ago.
Improve this question
With Github one can write a well-formatted README.md file and document to present the project. Also, there are wiki pages for user to collaborate. I'm wandering what would be an optimal workflow, even for non tech users, to make use of the GitHub platform to write a collaborative book.
How to use markdown but then enhance it by applying a stylesheet, make PDF out of it, organise chapters, have a public site (gh-pages) out of it and so on? Is there such a project or tool chain for GitHub?
In other word, how to easily write a collaborative book with a nice html and PDF output in GitHub? Thanks.
Edit: GitBook has changed significantly since I first wrote this answer. PDF support has been dropped, and the CLI toolchain has been abandoned in favour of a proprietary service:
As the efforts of the GitBook team are focused on the GitBook.com platform, the CLI is no longer under active development.
In mid-2019 mdBook is a good option, though it doesn't natively support PDF. If you have Rust and Cargo installed you can simply
cargo install mdbook
to get started.
Original answer:
This is exactly what GitBook is designed for:
GitBook is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc).
It supports PDF output out of the box, as well as online publishing on its own web platform.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 4 years ago.
Improve this question
I'm writing documentation for a GitHub project and wondering where should I write it to. There seems to be three options: GitHub Pages, GitHub Wiki or a set of Markdown files in the repository (e.g. under docs/ directory) similar to the README.md. Understandably I don't want to write the same documentation to multiple places so I have to pick one.
So what are the differences, pros and cons between the options? Any experience or thoughts about using them especially for project documentation? Also is there other options in addition to the three?
that is a very good question which I personally decide on a change-frequency and number-of-contributors basis.
As an example: in one of our projects (a c++ library) we create a HTML documentation with doxygen once in a while (e.g. while updating the master release branch). That's a perfect match for quasi-static gh-pages. In addition you get a sub domain for it http://<user>.github.io/<project>/ and you can register your own domains on top of it.
An other project contains developer and user documentation (a C++ program). I personally prefer to provide a main workflow for developers in .md files to keep them consistent with the mainline development. Changes will be reviewed by pull requests first.
But for user documentation we choose the build-in wiki since it is very easy to edit and modify - one can even allow modifications by non-members of a team.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
I found an interesting project on GitHub (a PHP Library) and I'm currently working on improving it.
I'm making big changes in the guy project. I'm changing the lib's architecture, fixing some bugs, adding some features, refactoring...
Since the changes are big, I don't plan to make a pull request for the guy to push my changes to his repo.
So here's my question: Should I fork his repo, delete everything in it and push "my" code, or create a new repo and just make a link in the Readme informing people that this project is based on the guy's one?
You are referring to the original meaning of a fork:
a project fork happens when developers take a copy of source code from one software package and start independent development on it, creating a distinct piece of software
If your changes are so different from the original codebase, then your second option looks ok: new repo, and reference to the old one in the README.
A "GitHub fork" really makes sense when you want to collaborate back to the original repo.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
For the past several years, I've been making small (single file, 1-500 line) scripts (mostly bash & python) to automate random tasks (usually scientific data analysis). Most of these end up being one-offs, but sometimes I want to go back and revisit/change something, or end up with a rather unwieldy script that could benefit from some sort of version control. I should note that all of these scripts are done solely on my own, and don't necessarily need to be share-able.
Which type of versioning (SVN,CVS,git,Mercurial..) Has the simplest command structure/syntax for my use case? More importantly, the machines I connect to are behind rather finicky kerberos walls, so I'm not looking for any sophisticated server-based implementation.
I found this thread from 2010 asking a similar question, though it didn't really talk about specific options, just whether or not I should be using a single repository.
In short, which versioning system allows for simple same-directory approach with minimal bells & whistles (only checkouts and commits needed)?
Should I set up some sort of subversion/CVS/git repository and just throw everything in?
Yes.
For your use-case, I suppose, SVN can be best choice (with URL-based access to every object in repo you can easy and fast get access to any single file any revision of file and for your linear history "not the best" merge in SVN isn't problem). Local file:///-based repository will require minimum of maintenance. You can use single-repository, flat tree (all files in /trunk)
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 2 years ago.
Improve this question
I am contemplating writing a useful article in a field of my interest. There are many others (about 10-15) people interested in peer reviewing and collaborating on the same. I am not a prolific programmer, but I understand how GitHub works for version control.
Can I use it for writing a 4-5 page collaborative article (version control is very important part) or do you think a better alternative exists?
You certainly could, but I don't know if it's the best choice. A couple of questions come to mind. Is this a text-based document format or are you planning on doing your writing in something like MS Word? If the former then I think it could work well. If the latter I would say it may be less effective.
What about your other collaborators? Are they savvy enough to use a DVCS? That would have some influence as well. I don't know how strongly you need the document versioned, but I could see using git as overkill.
I've found that using Google Docs works well and has a revision history, although it's obviously not as robust as would be found in a VCS.
I think it would work great. The Ruby on Rails guides are on a publicly write/readable repository at GitHub, for instance. You get get Git things for free (branches, blame, general version control features), plus you'll have a reliable backup and publishing mechanism if you like.
Given that the contributers are computer literate enough to successfully use Git, that is.
If you write it in Markdown, you can throw inline HTML into it (just by itself like you can do on Stack Overflow). Easy to write, easy to style, etc.
You can, but on the other hand:
Most wikis allow rich-content pages easyly, are ready for collaborative editing and have versioning and version-management embedded in the core.
One promissing recent development is penflip (https://www.penflip.com/) which was created with the idea of being a "github for text".
Check this article to learn about the author's ideas http://madebyloren.com/github-for-writers
Consider using google docs. They have some kind of version control. And it is much more suitable for this kind of work.