Project

General

Profile

Actions

Feature #1612

closed

Sphinx for docs

Added by Victor Julien almost 6 years ago. Updated almost 5 years ago.

Status:
Closed
Priority:
Normal
Assignee:
Target version:
Effort:
Difficulty:
Label:

Description

Move version dependent docs, like keyword docs to sphinx.


Subtasks 13 (0 open13 closed)

Feature #1613: document sphinx switchClosedJason Ish12/02/2015Actions
Feature #1620: User guide conversion to Sphinx: 8. Suricata RulesClosedJason Ish12/04/2015Actions
Feature #1621: Docs: Convert Section 6. Command Line OptionsClosedJason Ish12/04/2015Actions
Feature #1622: Docs: Convert Section 9. Rule Management with OinkmasterClosedJason Ish12/04/2015Actions
Feature #1623: Docs: Convertion Section 10. PerformanceClosedJason Ish12/04/2015Actions
Feature #1624: Docs: Convert Section 11. ConfigurationClosedJason Ish12/04/2015Actions
Feature #1625: Docs: Convert Section 12. ReputationClosedJason Ish12/04/2015Actions
Feature #1626: Docs: Convert Section 13. Init ScriptsClosedJason Ish12/04/2015Actions
Feature #1627: Docs: Convert Section 14: Setting up IPS/Inline for LinuxClosedJason Ish12/04/2015Actions
Feature #1628: Docs: Convert Section 15. OutputClosedAndreas Herz12/04/2015Actions
Feature #1629: Docs: Convert Section 16. File ExtractionClosedJason Ish12/04/2015Actions
Feature #1630: Docs: Convert Section 18. Public Data SetsClosedJason Ish12/04/2015Actions
Feature #1631: Docs: Convert Section 20. Using Capture HardwareClosedJason Ish12/04/2015Actions
Actions #1

Updated by Victor Julien almost 6 years ago

We should probably create various sub-tickets with this one as parent to divide up the effort.

Actions #2

Updated by Jason Ish almost 6 years ago

Yes, probably break it down based on the major sections at https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Suricata_User_Guide.

I've done a few more items on "8. Suricata Rules" so it might make sense for me to keep going down that section.

Some are very fast to convert, others, particularly where tables are involved are a little more tedious.

Does Redmine support real "sub-isses"?

Related: I'm not sure if we should bother with the development docs in Sphinx. Thoughts? Developers should be developing against bleeding age, and I wouldn't want someone developing against old developer docs. So perhaps those are best kept on the wiki, at least for now. Concentrate this effort on the user guide?

Actions #3

Updated by Victor Julien almost 6 years ago

Agreed on limiting this to the User docs. Also we can exclude a bunch of things, like 'misc guides'.

Wrt sub tickets, the procedure is that you create a regular ticket and then set it's parent field to this ticket.

Actions #4

Updated by Andreas Herz almost 6 years ago

Jason Ish wrote:

Related: I'm not sure if we should bother with the development docs in Sphinx. Thoughts? Developers should be developing against bleeding age, and I wouldn't want someone developing against old developer docs. So perhaps those are best kept on the wiki, at least for now. Concentrate this effort on the user guide?

I agree on concentrating on user guide first, but unless i missed something, i would also go on with developer docs, too.

I see no gain in splitting, especially when keeping the docs up to date it might be easier if it's in the .rst format for sphinx. So instead of editing the wiki pages in redmine manually, you could automate it better within the sphinx scenario.

Actions #5

Updated by Jason Ish almost 6 years ago

Andreas Herz wrote:

Jason Ish wrote:

Related: I'm not sure if we should bother with the development docs in Sphinx. Thoughts? Developers should be developing against bleeding age, and I wouldn't want someone developing against old developer docs. So perhaps those are best kept on the wiki, at least for now. Concentrate this effort on the user guide?

I agree on concentrating on user guide first, but unless i missed something, i would also go on with developer docs, too.

I see no gain in splitting, especially when keeping the docs up to date it might be easier if it's in the .rst format for sphinx. So instead of editing the wiki pages in redmine manually, you could automate it better within the sphinx scenario.

Maybe I'm overthinking it, but with the user guide it makes sense to have the current state of the documentation snapshotted with that release, and staying that way. We don't have to have "if this version, do this.. If that version do that". Its specific to the version its included in.

What I worry about with developer documentation, if we do it the same way is some young dev is will follow the developers guide in the documentation with the release they are working from, then perhaps submit it to us. Practices could have changed, APIs will have changed, etc. Which is why I lean to keeping the developer guide out of the releases at least.

Now, at some point we may have 2 types of developer guides. We may have the one for developers working on Suricata itself (this is what I refer to above), and we may need a guide for those developing with Suricata - Lua plugins, Lua scripting, etc - now that should get versioned with the release.

Actions #6

Updated by Victor Julien almost 6 years ago

Lua docs are part of user docs in my thinking. Wrt dev docs, lets revisit that after we've done the user docs. Just converting the user docs is a big effort.

Actions #7

Updated by Andreas Herz almost 6 years ago

Jason Ish wrote:

Maybe I'm overthinking it, but with the user guide it makes sense to have the current state of the documentation snapshotted with that release, and staying that way. We don't have to have "if this version, do this.. If that version do that". Its specific to the version its included in.

That's what i missed, i didn't see the release specific doc and with that in mind i understand why you want to manage it differently. So let's see how it works for the user part and talk again how we can improve the developer guides as well. I just think it's better to work on files within version control like .rst format instead of the normal wiki, but that's just my personal view :)

Actions #8

Updated by Victor Julien almost 5 years ago

  • Status changed from New to Closed

Merged into the git repo. I consider this ticket done. Thanks a lot guys!

Actions

Also available in: Atom PDF