Some Changes to be made to CP Site (main and forum) and related proposals

Projects Documentation
#11

Wether Kevin was using his own tool or not (I think he used the exact same core code, which is phpdoc-parser), the result is 100% the same:
It is a WP (or CP) site with code generated doc and user added comments

And that is non-git-compatible.

:slight_smile:

I have the WP parser from https://make.wordpress.org/docs/handbook/devhub/ (the whole system, this is not just a plugin or one-code install) setup locally since months already. It takes a few hours to setup perfectly. @azurecurve FYI if you want to try, above link should include all necessary info.

Yes, this works only when following WPCS (Documentation AND code standards) are followed. Which WP and CS do, and as long we use WPCS, there’s no issue.

About JS, we could probably extend this, but it needs something else than phpdoc-parser
I think it is a great idea for a second stage, again putting CP into a “more evolved” light.
Thus I will research about this.

But first, we need to solve this problem with “Git driven doc”, which is great for user documentation but unreasonable for machine generated doc.

#12

Nope I developed my own parser specifically for ClassicPress. I did not like the core one, as it missed many things.

I also built a custom scraper to incorporate the docs as they were at the time of 4.9. So all the user notes are there from that time.

Now I put the whole doc system up twice, and not much interest was expressed. There was also much discussion of using the GitHub Doc system. There was not one person interested in setting it up as the doc system for Classic Press. So I basically gave up.

Everybody has their own ideas on what the doc system should look like and do, and what tools and scripts should be used. So you usually have to fight through all that negativity to get anything done in open source. I’ve tried many times, this was the last effort I will make. Open source is just not for me.

Also of note, I am a self taught coder, so the scripts, while they work, don’t always follow best practices. Usually when someone looks at my code, they turn green ( and it’s not “Green with envy” ;). Then they start re-coding everything.

But I will tell you the entire doc system can be set up in about 2 hours. And maintained every time a release is made, in about 2 hours.

TBH I just wanted to help…but as usual … it did not work out.

I will however continue to code as I do love it :slight_smile:

#13

Thanks for the info, @kevinhaig

As for “incorporate the docs as they were at the time of 4.9”, this should be possible to do with the WP scraper if we simply run it over a 4.9 (or better: ClassicPress) install.
What is trickier is the user notes, not sure how to get those.

I personally don’t care what tool we use. What cannot be is that due to “opinions”, we end up not having a doc.
And there is not much to opinate here actually. The Code Doc Blocks are there, and it is silly to not use them, thus, human written doc is not the way to go. This is just a fact. Also fact is, that converting a “WP/CP” post doc to Github is again a silly, unnecessary additional step.

If we simply take the formula for perfection, which is “As long you can take away something without breaking the functionality, it is not perfect”, we can exclude opinions and discussions.
The minimal, working version of such DOC is to let a machine scan the code and build doc from the Code Doc Blocks.
Everything else added to that, is not making it more perfect, but more bloated (and perhaps fancier).

I totally understand your frustration and understand your reasoning. I would prefer to not use a “wheel re-invented” solution, but on the other hand, if your system is able to do all what you described, I am interested in using it.
The main question here is, if you would be able, and willing to, share the source so I can build this for CP finally.
If you are, would you mind to share this with me?

I am a self thought dev as well, and I will not belittle you because of possible coding approaches because I did not forget where I started. I did not forget that I knew nothing about code a few years ago, and still know nothing, this is just my live style. You never learn out.

What is “bad code” can be rewritten and there is nothing bad with that. The credit goes to you as the initiator and the one with the will and persistence to actually create it rather than fuss around with opinions and discussions. Don’t misunderstand me, I am aware that a democracy lives on opinions and discussions, but if people die because the society is not agreeing on how to perform a surgery or respond to a cataclysm, we can as well go back into caves. Without going into politics, this is IMO one of the main reasons why democracy is not the final solution :slight_smile: - votes can be influenced, lobbied and in the end, it is just a ochlocracy. Specially when we vote but do not have constructive contributions to make. I am from a country that heavily suffers under this effect and ended up putting up laws that directly oppose Human rights just because “the majority voted yes”.

So, enough of this off-topic reasoning.

I don’t think there is much to discuss. The requirements are clear, we need a DOC. And it needs to be easy to maintain, and not go over 5 edges to achieve the goal we can achieve with one edge.
Thus, It is perfectly OK to have a GitHub stored user documentation with How To’s and the like, but for Code DOC, we will plain simple need a (plain simple) CP Install where we can manage these code docs

I am not sure if I miss something here but it shouldn’t take too much work to actually create such install, put it in a subdomain of CP, and Link to it. The current doc.cp.net (user doc) can still proceed existing. We can create a codex.cp.com or developer.cp.com for the code-doc

#14

This I can and will do on my own

  1. Done
  2. Done
  3. Done
  4. Done
2 Likes
#15

If there are tools which produce the required content, but which isn’t Git compatible, isn’t the solution to not use Git for it? This sounds like square peg, round hole problem; if the tools output html content, lets serve it through a site doing html…

2 Likes
#16

Exactly! Just what I say. And for that we need a WP or CP driven install.
As said, we can still use Git for user doc, such as how to and whatnot. That is actually already running here and can stay http://docs.classicpress.net/

I already asked for a sub install but the objection was made that “we already have http://docs.classicpress.net/, which runs on git”.
This, is the only thing stopping me right now from finally getting up that DOC.

Creating a ClassicPress Codex
#17

Breaking this element of the conversation into a thread of its own.

2 Likes
#18

8 posts were split to a new topic: Docs Site - GitHub Plugin Usage

#19

Most of the GitHub discussion is way off topic from this thread, so I have moved it to a new thread.

#20

In terms of this thread, I think we are all good. Let’s schedule some time to chat about the outstanding bits, and continue the convo re the codex on that thread.

#21

@wadestriebel not sure about this but wouldn’t it be better to link about to where we describe our stuff, and remove committee from the footer, because there’s no committee
The about currently links to a list of team leaders as far i see, which could be understood as a committee - but is somewhat misleading - see my opening post section “this I can’t do”

I think best is simply remove the committe link, link about to that page and in that page link to that “list of team leaders”
I can add the links inside the page but I can’t edit tje footer

#22

I think we can remove the Team Leads to be honest, being a little blunt but most the team leads haven’t been active for a while so I would rather just remove it and allow people to help out as they see fit.

Thoughts?

3 Likes
#23

Agreed. Let’s get some momentum going organically instead of by designating specific roles (which has led effectively — though not intentionally — to vetoes).

4 Likes
#24

Fully agreed.

  • Remove the stuff currently linked to in about.
  • remove committe link all together
  • add the link currently used for committe to about

That’d conclude the major points of this tick
Apart of the header but it’s not super urgent I think.
Although would be nice to have :upside_down_face:

3 Likes
#25

I have WP parser setup in a dev environment; everything seems to work and everything was extracted.

I also installed the other plugins from that age and found the handbook one is block dependent.

2 Likes
#26

@azurecurve - did you see Docs Site - GitHub Plugin Usage?
I am already adding theme styles and bells and whistles - the content is ready.

However I only plan to add the code for now, the handbook … we may add but needs a tad editing.

1 Like
#27

Yes, I did see that you were making good progress.

I thought it might be useful for a second person to have the parser setup and available (plus I like messing about with stuff).

It also gives me an environment to work for helping with any of the parts we need to write.

2 Likes
#28

I’ve to apologize for my previous comment
It probably came off the wrong way.

Reading it now it seems I intended to “stop” you from doing valuable work or even worse compare results :disappointed:, which of course wasn’t in my intention at all.

It’s of course nothing but right to have more than one instance (we’ll need it) and there’s nothing else to say but:
Great work, and my apologies to come off the wrong way. I should have chosen my words wiser.

Thanks - not only for the contribution on weekend but also for giving me a chance to “reiterate” my own words which clearly sometimes need more thought.

#29

No problem at all.

1 Like
#30

A bit late to see this and reply, but yes to all proposed changes from me. Let me or Wade know what you need in order to keep moving forward, and for any changes to the backend of the site (code, plugins, themes, etc) please keep me in the loop.

1 Like