I am working on a small toy project who is getting more and more releases. Until now, the documentation was just a set of pages in the wordpress blog I setup for the project. However, as time passes, new releases are out and I should update the online documentation to match the most recent release.
Unfortunately, if I do so, the docs for the previous releases will "disappear" as my doc pages are updated to the most recent version, therefore I decided to include the documentation in the release package and to keep the most recent documentation available online as a web page as well.
A trivial idea would be to wget the current docs from the wordpress pages, save them into the svn and therefore into the release package, repeating the procedure at every new release. Unfortunately, the HTML I get must be hacked by hand to fix the links (or I should hack wordpress to use BASE so that the HTML code is easily relocatable, something I don't want to do).
How should I handle the requirements of having at the same time:
user-browsable documentation for the proper version included in the downloadable package
most recent documentation available online (and properly styled with my web theme)
keep synchronized between the svn and the actual online contents (in wordpress, or something else that fits nicely with my wordpress setup)
easy to use
Thanks
Edit: started a bounty to see if I can lure more answers. I think this is a quite important issue, and it would be nice to have multiple hints and opinions for future readers.
I would check your pages into SVN, and then have your webserver update from its local SVN working copy when you're ready to release. Put everything into SVN--wordpress, CSS, HTML, etc.
WGet can convert all the links in the document for you. See the convert-links option:
http://www.gnu.org/software/wget/manual/html_node/Advanced-Usage.html
Using this in conjuction with the other methods could yield a solution.
I think there are two problems to be solved here
how and where to keep the documentation aligned with the code
where to publish the documentation
For 1 i think it's best to:
keep the documentation in a repository (SVN or git or whatever you already use for the code) as a set of files, instead of in a db as it is easier to keep a history of changes (an possibly to stay in par with the code releases
use an approach where the documentation is generated from a set of source files (you'd keep the sources in the repository) from which the html files for the distribution package or for publishing on the web are generated. The two could possibly differ, as on the web you'd need to keep some version information (in the URL) that you don't need when packaging a single release.
To do "2" there are several tools that may generate a static site. One of them is Jekyll it's in ruby and looks quite complete and customizable.
Assuming that you use a tool like jekyll and keep the files and source in SVN you might setup your repo in this way:
repo/
tags/
rel1.0/
source/
documentation/
rel2.0/
source/
documentation/
rel3.0/
source/
documentation/
trunk/
source/
documentation/
That is:
You keep the current documentation beside the source in the trunk
When you do a release you create a tag for the release
you configure your documentation generator to generate documentation for each of the repo/tags//documentation directory such that the documentation for each release is put in documentation_site/ directory
So to publish the documentation (point 2 above):
you copy on the server the contents of the documentation_site directory, putting it in the same base dir of your wordpress install or linking from that, such that each release doc can be accessed as: http://yoursite/project/docs/relXX/
you create a link to the current release documentation such that it can always be reached as http://yoursite/project/docs/current
The trick here is to publish the documentation always under a proper release identifier (in the URL, on the filesystem) and use a link (or a redirect) to make sure that the "current documentation" on the web server points to the current release.
I have seen some programs use help & manual. But I am a Mac user and I have no experience with it to know if it's any good. I'm looking for a solution myself for Mac.
For my own projects, if that were a need, I would create a sub-dir for the documentation, and have all the files refer from the known-base of there relatively. For example,
index.html -- refers to images/example.jpg
README
-- subdirs....
images/example.jpg
section/index.html -- links back to '../index.html',
-- refers to ../images/example.jpg
If the docs are included in the SVN/tarball download, then they are readable as-is. If they are generated from some original files, they would be pre-generated for a downloadable version.
Archive versions of the documentation can be unpacked/generated and placed into named directorys (eg docs/v1.05/)
Its a simple PHP script that can be written to get a list the subdirs of the /docs/ directory from the local disk and display a list, and highlighting the most recent, for example.
Related
Recently, I found out, that the official bzip page has changed (http://www.bzip.org/index.html). I had a script, which took the source code from bzip.org and compiled it. Now, the source code and all other stuff are not anymore on this site.
I found, that there is a possible copy of that code at https://github.com/enthought/bzip2-1.0.6.
But I am unsure, if this is the real bzip2 code without any harmful changes. Is there another official bzip.org site or another site, where I can download the official source code?
You may still access the source from web archives
https://web.archive.org/web/20180624184806/http://www.bzip.org/downloads.html
So here's a question. I'm new to Sylius, and am working on some simple CSS updates. I have a local copy of Sylius running with the built-in webserver: server:run. I also have a development server on Digital Ocean, which runs an (almost) identical copy of Sylius, aside from the configs of course.
Something strange is happening with my CSS update, however. I made a change to .navbar-brand within web/assets/compiled/backend_backend_4.css.
This change showed up immediately on my local. On the development server, however, when pulling down the change (git), and verifying that it now exists in that file, the change doesn't seem to propegate. It's effects aren't shown, inspecting the stylesheet doesn't show them, and furthermore viewing the css file sourcecode directly in the browser does not show the change. But on the filesystem it's definitely there.
I've tried clearing the cache, to no avail.
I also checked the assetic value in both config_dev.yml files, and verified they are both set to use_controller: true
Even still, I tried dumping assetic, to no avail.
So I'm wondering what's going on. Additionally, I realize that I probably shouldn't edit CSS files within a folder called 'compiled'. I'm sure there's a way to do that using a compiler, but I'm not yet familiar with the process and am just making minor changes and learning about caching so far.
Yes you are right you shouldn't be editing the compiled files.
You should edit the source files, then run gulp
or on my system i have to explicitly run npm run gulp
I've documented the solution that worked for me here. It didn't involve Gulp at all, but instead uses Assetic:
Assets need to be installed as hard copies first (I'm not quite sure
what this does exactly, but it seems like an important step because
it copies a lot of assets to places. Documentation was unhelpful but
it was suggested on Stack Overflow somewhere.):
app/console assets:install web
Assets should be edited in web/bundles/[bundle-here]/css or js. This
is frequently within syliusweb if it has to do with page styles /
layouts.
Hint: These assets are referred to in files such as
src/Sylius/Bundle/Resources/views/Backend/layout.html.twig (see the
opening:
(% stylesheets
tag, or search universally for this tag).
Within this tag, you'll see that stylesheets have an output to the compiled folder, but also list the
bundles where they pull their original css from. You should edit one of the source css files, if you'd like your changes to end up in the destination css.
After editing assets, dump assetic:
php app/console assetic:dump
Note - it is also possible to set an assetic watcher on these assets
(google to find out how, think it's a -w flag somewhere), but this is
said to only work in development mode, as it should.
After dumping assetic, the assets from the source bundles compile into their assets/compiled versions, usually combining multiple stylesheets. You should now see your asset refresh!
I try to write a file store based on libgit2.
Software snapshots should be saved as branches mysoftware and specific versions committed and tagged. Then later I want to checkout the tags to different directories.
When looking at git_checkout_tree, it seems like there is only one working tree for a repository and thus it does not even seem possible to checkout multiple working trees concurrently.
Is this correct!?
EDIT:
Additionally, I would like for this thing to work on Windows without the need for cygwin!
The git_checkout_opts structure in libgit2 contains a target_directory option that will allow git_checkout_tree() to write to a different directory instead of using the default working tree for the repository. This would allow you to custom build a solution with libgit2 that maintained multiple checked out copies.
Without using that option, a libgit2 git_repository object expects there will be just one working directory and looks to the core.worktree config option if it isn't the "natural" working directory for the repository.
The git-new-workdir tricks with symlinks in the .git directory don't work great with libgit2 right now, I'm afraid, and particularly doesn't work well on Windows. I'd love to see this addressed, but it isn't too high on my priority list.
Git doesn't support this natively, but you can use git-new-workdir to do it.
symfony1.x followed a good standart that the whole framework lies somewhere outside and is available to any project. Today I started to read symfony2 documentation and actually downloaded the 'with vendors' 2.0.1 package which is presented on download page. After opening the package I was a bit surprised of what I've seen. But after looking around the package I found that the only folder I need is 'vendors' one - so I copied its content to my '...\lib\vendor\symfony2' folder (near '...\lib\vendor\symfony' and '...\lib\vendor\ext'). I added it to include path and proceed reading documentation. And then I found a problem - a command listed 'php app/console generate:bundle --namespace=Acme/HelloBundle --format=yml' produced simple questions. Did they miss to explain how to generate a project (structure, preconfiguration, command-line files, etc)? And what about '.bat' and '.sh' files?
Symfony2 is very, very different than symfony 1 - especially when it comes to the directory structure. You can't simply drop in the vendors dir and expect it to work. This page explains how to setup a new Symfony2 project.
I recommend you to forget Symfony... and to think with Symfony2 about another think completely different than S1.
Installation is really simple and you will need some advanced PHP knowledge just to understand how it works... But if you have worked with S1, I expect you will have not much problems :)
I just created my first trac project, but I don't want the sample data, how can I disable that.
I read the documentation and there is the wiki remove command. do I have to use this for all pages? Are there easy way to disable the sample wiki?
Modification of the behavior of
trac-admin <path_to_env> initenv seems not even worth the hassle, because you only need to type
trac-admin <path_to_env> wiki remove '*'
into a system terminal to get rid of all default Trac wiki pages. You'll see a list of all deleted page names for confirmation. But you always make a db copy before messing with the db anyway, don't you?
Sorry but there is no easy way to diable the sample wiki in trac. I'm pretty sure this can be done with a custom script, though.
Trac stores the default pages imported into the wiki of a new environment as plaintext files in the file system.
For example, on my Gentoo box they can be found in /usr/lib64/python2.7/site-packages/trac/wiki/default-pages/.
You can move these out of the way (or just keep those you want) before calling trac-admin projectname initenv and it will only create the pages that are in the ´default-pages` directory at the time of the call.