Comments (12)
It looks like to implement this, we may need to pre-generate the documentation since we would need to checkout each version to get the contents.
What are your thoughts on creating a way to pre-generate all the documentation, thus making a sort of static site? We could leave the dynamic router in front of the static HTML to keep URLs the same between dynamic/static docs. We could expose a configuration option and an artisan command that would generate all the docs.
from codex.
It would be useful if the documentation repository's branching model could match the project repository's and generate matching documentation.
I guess I'm a little fuzzy on the functionality/purpose behind this. What would the use case be (ie, how would it be used)?
It sounds cool, but it also sounds a bit overly complicated to set up rather than simply creating a couple directories and writing documentation.
from codex.
Yeah, I agree that it would add quite a bit of complication. Here's my use case:
- We have a project repository
project
and it has the following tags and branches: 1.0.0, 1.1.0, master - We have another repository called
project-docs
and it has the same tags and branches: 1.0.0, 1.1.0, master
The documentation repository follows the project's branching/tagging model. If you want docs for project
version 1.0.0, you checkout project-docs
at the 1.0.0
tag. The reasoning here is often times, the documentation between 1.0.0 and 1.1.0 is only very slightly different (so why actually duplicate the files, DRY type thing). Additionally, working this way allows you to leverage git very easily: you can diff documentation between versions with git diff 1.0.0 1.1.0
, you can merge documentation changes between branches with git merge
, etc.
So, set up for this within Codex might work something like:
- Install Codex
- "Install" the documentation repository into Codex: Open up the storage directory,
git init
andgit remote add origin [email protected]:project-docs.git
andgit pull --mirror
- Edit
codex.php
configuration file to let Codex know that it should look at the git repository's branches and tags (rather than the folder structure) to determine versions. - Run an artisan command like
./artisan gen-docs
which would go through, check out all the branches and tags, and generate static HTML files that would then be served through the CodexController.
Steps 3 and 4 don't yet exist. Step 4 could also be leveraged for regular "folder-based" documentation, as well, to improve performance (could be a straw man argument-- I dont know if there is a point where Parsedown will be noticeably slow in rendering a document)
Really there are two distinct features: pre-compilation of docs, and using git for versioning. Do you think either of these features belong in Codex?
from codex.
I see.
I don't think we'd need a gen-docs
command specifically. A simple method to serving pre-generated static pages would be to just implement caching on the page - which would cache the generated HTML page for X amount of minutes. This would be a simple update as well (which I believe the Laravel website does for their documentation too).
Pulling down a git repository specifically for the documentation files would be cool though. I can't think of a way to somehow automate this via PHP/Laravel though.
from codex.
Good call about the caching, that's a much better solution.
As far as automating Git stuff, Composer implements some stuff to mess with Git: https://github.com/composer/composer/blob/master/src/Composer/Util/Git.php. We could do similar.
Let me see if I can get a minimal version working, then we can use it as a starting point for further discussion regarding whether it actually fits Codex's scope and if we can simplify and automate things.
from codex.
👍
from codex.
I've added cache support with commit 289caca.
from codex.
@tyler-sommer I've added the ability to choose which driver method you'd like to use (opening the door to easily switch between flat and git through the Codex config file) - I've also written documentation on extending and creating you're own driver. Should provide a solid base to work in Git integration.
Commit: fca399e
from codex.
Thanks, @kaidesu, I appreciate it. I'll take a look and incorporate the changes into my code.
from codex.
Works pretty great so far~ I got the Codex Docs repository initialized with the current codex documentation (branched 1.0.0 and master). Once things are further tested and the code is cleaned up, I think we'll be good.
The only tweak I can see right now is adding the ability to choose if you want the master branch to be the default version or default to the latest stable x.x.x branch.
from codex.
Awesome, I'm glad to hear it's working! I've got it up and running at niceframework.com and I'm working on getting https://github.com/terramar-labs/packages-docs up somewhere as well. Being able to specify a default version would be killer!
from codex.
I've cleaned up the code quite a bit, fixed a few bugs, and implemented an AbstractCodexRepository class to take care of some of the methods that were duplicates (and most likely will always be for any storage driver implementation).
With that, I'll be releasing v1.1.0 very soon if there are no major issues with the latest master branch.
I'm going to go ahead and close this issue and call it complete though. Thank you for the contribution and time spent working on this! I had a blast~
from codex.
Related Issues (20)
- Authentication HOT 3
- Turn this into a package HOT 9
- Git driver does not pull in newly created branches automatically
- Refactor version sorting logic
- make "kzykhys/git" optional
- Caching can not work HOT 1
- Handle spaces in manual and version directory names
- always keep table of contents visibile
- Undefined variable: `siteName`, run on Homestead 2.0 HOT 2
- http://codex.caffeinated.ninja does not work at the moment HOT 2
- Add anchors to headers.
- Change markdown meta notation and parsing HOT 5
- I really love the theme you have in your website http://codex.caffeinated.ninja, any way to get it HOT 2
- Couldn't get it installed HOT 4
- Exception on first run HOT 2
- Enable / Disable Menus
- Improve speed. Too many objects are instantiated while used for nothing
- Documentation HOT 1
- Empty Search
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from codex.