New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a ``mkdocs json`` that builds a site in json. #128

Merged
merged 3 commits into from Oct 9, 2014

Conversation

Projects
None yet
4 participants
@ericholscher
Contributor

ericholscher commented Aug 22, 2014

This is mainly for Read the Docs -- but it would be neat to have mkdocs build both the JSON and HTML versions of docs, so when you hit a URL, you can just change the .html into a .json and you get the JSON representation of the files.

This doesn't have tests currently, just curious what folks think about it before I invest too much time.

@d0ugal

This comment has been minimized.

Member

d0ugal commented Aug 22, 2014

Looks like this needs a rebase, but I can't see why. Otherwise, LGTM but I'll wait for Tom to weigh in as this in a new feature.

@d0ugal d0ugal closed this Aug 22, 2014

@d0ugal d0ugal reopened this Aug 22, 2014

@d0ugal

This comment has been minimized.

Member

d0ugal commented Aug 22, 2014

Sorry - accidental close. That was my dog!

@tomchristie

This comment has been minimized.

Contributor

tomchristie commented Aug 22, 2014

@ericholscher - So is this for search or for the API?

@tomchristie

This comment has been minimized.

Contributor

tomchristie commented Aug 22, 2014

(Or both)

@d0ugal

This comment has been minimized.

Member

d0ugal commented Aug 22, 2014

@tomchristie This was in buffer for #mkdocs when I looked at IRC this morning.

<ericholscher> okay I have 2 things I need in mkdocs, I'll try and find time to add them this week
<ericholscher> er, maybe next week :)
<ericholscher> I think they will be easish
<ericholscher> theme_dir needs to allow multiple directories
<ericholscher> which should be like a 2 line change
<ericholscher> then I need a way to output json data of each rendered markdown file -- which ya'll will likely need for search anyway
<ericholscher> (which is what I'm using it for)
@tomchristie

This comment has been minimized.

Contributor

tomchristie commented Aug 22, 2014

Is the RTD search server side based?

@tomchristie

This comment has been minimized.

Contributor

tomchristie commented Aug 22, 2014

Obv on it's own I'd be meh about this, but if it's a blocker to being able to get it onto RTD then it's clearly worthwhile. :)

@tomchristie

This comment has been minimized.

Contributor

tomchristie commented Aug 22, 2014

Needs adding into help, adding to documentation.

@d0ugal

This comment has been minimized.

Member

d0ugal commented Aug 22, 2014

I think it must be serverside, as they have cross project search like this:
https://readthedocs.org/search/project/?q=models&selected_facets=project_exact%3ADjango

@edbrannin

This comment has been minimized.

Contributor

edbrannin commented Aug 22, 2014

The merge conflict is because mkdocs/mkdocs is now mkdocs/main.py.

@d0ugal

This comment has been minimized.

Member

d0ugal commented Aug 22, 2014

@edbrannin of course, thanks :)

@ericholscher

This comment has been minimized.

Contributor

ericholscher commented Aug 22, 2014

Yea, this is for generating search indexes on RTD -- it was just the
simplest way I could see of doing it. I think normal users will appreciate
the ability to build json objects too, since it's good for doing lots of
other things with the docs (eg. wrapping the content in your own styles and
just serving it from the json files)

On Fri, Aug 22, 2014 at 6:56 AM, Dougal Matthews notifications@github.com
wrote:

@edbrannin https://github.com/edbrannin of course, thanks :)


Reply to this email directly or view it on GitHub
#128 (comment).

Eric Holscher
Maker of the internet residing in Portland, Or
http://ericholscher.com

@@ -30,6 +30,9 @@ def main(cmd, args, options=None):
elif cmd == 'build':
config = load_config(options=options)
build(config)
elif cmd == 'json':
config = load_config(options=options)
build(config, dump_json=True)
elif cmd == 'gh-deploy':
config = load_config(options=options)
build(config)

This comment has been minimized.

@d0ugal

d0ugal Oct 6, 2014

Member

'json' needs to be added to the help output in the else clause a few lines down.

@d0ugal

This comment has been minimized.

Member

d0ugal commented Oct 6, 2014

Added one comment inline about help output. Could we also include the json command in the tox run by adding it to tox like https://github.com/tomchristie/mkdocs/blob/master/tox.ini#L12? It could probably be added to the same environment.

This will then at least give us an integration tests for this.

@d0ugal d0ugal added the Update needed label Oct 6, 2014

@d0ugal d0ugal added this to the 0.10.0 milestone Oct 7, 2014

@d0ugal d0ugal removed the Update needed label Oct 8, 2014

@ericholscher ericholscher force-pushed the ericholscher:json_builder branch from b8b8df6 to 77a29a7 Oct 9, 2014

@ericholscher

This comment has been minimized.

Contributor

ericholscher commented Oct 9, 2014

Rebased and pushed up the above suggestions. Build passed, so it seems happy.

@d0ugal d0ugal merged commit b14c834 into mkdocs:master Oct 9, 2014

1 check passed

continuous-integration/travis-ci The Travis CI build passed
Details
@d0ugal

This comment has been minimized.

Member

d0ugal commented Oct 9, 2014

The one gotcha is that you need to add json to Travis too. I've done this.

afc1f28

@d0ugal

This comment has been minimized.

Member

d0ugal commented Oct 9, 2014

Thanks!

@tomchristie

This comment has been minimized.

Contributor

tomchristie commented Dec 1, 2014

Be really good if we could unify this and the tipue JSON. Right now it's a bit weird that we have a user-facing command that's really intended only for RTD behind the scenes consumption - (it's not obvious to me as a user what the format is or why it's there.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment